# @pencroff-lab/kore

> Edition: v0.7.1 (latest)
> Documentation for released version 0.7.1.
> Canonical URL: https://kore.lab.pencroff.com/

> TypeScript core utilities library providing value-based error handling
> with a Go-style `Err` type and `flow`, a tier of free functions over
> `ResultTuple<T>`. Published to npm as a dual ESM/CJS package.
> The `Outcome<T>` class is deprecated and frozen since v0.7.0.

Every link below resolves inside the installed package, relative to the
package root (`node_modules/@pencroff-lab/kore/` in a conventional install;
resolve the package directory rather than assuming a flat layout).

## Start here

- [Documentation index](https://kore.lab.pencroff.com/): entry point for all shipped documentation

## Core subset

Start with `ok`, `fail`, `attempt`, `map`, `flatMap`, `mapErr`, `defaultTo`,
then `pipe` with `onOk` / `onErr`. Fallible callbacks return tuples; `map`
returns data. Async operations, whole-tuple hooks, collections and serialization
are advanced operations; see the [flow reference](https://kore.lab.pencroff.com/api/flow/).

1. Test `error === null` before using the success value. Never test value
   truthiness: `ok(null)`, `ok("")` and `ok(undefined)` are successes.
2. Never discard a result tuple, including a resolved async result. Handle its
   error or propagate the tuple to a caller that will handle it.
3. Wrap `JSON.parse` with `attemptValue` and `response.json()` with
   `attemptValueAsync`, then validate the resulting unknown data with a schema
   or type guard. The adapters always add an envelope: parsed `[7, null]` is
   data, not a success protocol returned by the parser. `attemptValue` rejects
   known PromiseLike returns; use `attemptValueAsync` for those callbacks.

Inferred fallible callbacks, pipeline stages and sources reject raw `any` and
`Promise<any>`. Explicit type arguments, preannotated callbacks/operator aliases,
and casts can erase those checks; JavaScript callers have no type protection.
Consumers need type-aware unsafe-any lint for returns, assignments, arguments,
member access and calls, together with `noFloatingPromises`. Promise lint alone
allows awaited or explicitly voided tuples to be dropped. v0.7.1 ships **no
downstream tuple must-use rule**; delivering one is a follow-up.

`pipe` and `pipeAsync` accept at most ten stages. Compose longer flows in typed
chunks. `effect` accepts only void/undefined callbacks: use `flatMap` for a
fallible side effect and `effectAsync` for awaited void work. These guarantees
have regression tests; comparison with disciplined `try/catch` on matched tasks
remains unmeasured.

## Core Modules

- [Err](https://kore.lab.pencroff.com/api/err/): Immutable, value-based error type with wrapping (cause chains), aggregation, hierarchical error codes, JSON serialization, and conversion to native Error. `Err.isErr` is nominal (`instanceof`) since v0.7.0; reconstruct wire data with `Err.from`
- [flow](https://kore.lab.pencroff.com/api/flow/): The primary API — free functions over `ResultTuple<T>` (`readonly [T, null] | readonly [null, Err]`): `ok`, `fail`, `attempt`/`attemptAsync`, `attemptValue`/`attemptValueAsync` for throwing value functions, `copy`, `map`/`flatMap`/`mapErr`/`effect` plus async forms, `ensure`, the `onOk`/`onErr`/`onTuple` stage factories, `pipe`/`pipeAsync` (up to ten stages), `defaultTo` (handler-only), `either`, `all`, `any`, `fromJSON`. Every fallible callback returns a `ResultTuple`; value adapters always envelope their data
- [flow test helpers](https://kore.lab.pencroff.com/api/test/): `expectOk` / `expectErr`, published from the `@pencroff-lab/kore/test` subpath only
- [Outcome](https://kore.lab.pencroff.com/api/outcome/): **Deprecated, frozen.** Monadic result container wrapping `[T, null] | [null, Err]` with map/pipe chains, combinators (all, any), side effects, and terminal operations. Callbacks follow the value protocol (`Err` = failure, `Outcome` = passthrough, anything else = the success value); `fromTuple`/`fromTupleAsync` are the only tuple entry points, and `toTuple()` is the only extraction
- [Logger](https://kore.lab.pencroff.com/api/logger/): Structured, level-filtered logging with pluggable transports and Err integration
- [dtStamp](https://kore.lab.pencroff.com/api/format_dt/): Compact, sortable date/time stamps for file names, log prefixes, and IDs
- [API overview](https://kore.lab.pencroff.com/api/): Every exported symbol, grouped by module

## Usage Examples

Generated from executable example tests, so every snippet is verified.

- [Err examples](https://kore.lab.pencroff.com/examples/err/): Error creation, wrapping, codes, serialization
- [flow examples](https://kore.lab.pencroff.com/examples/flow/): Boundaries, the callback protocol, transformations, pipelines, collections, serialization, input protection
- [flow test helper examples](https://kore.lab.pencroff.com/examples/test/): Asserting on result tuples
- [Outcome examples](https://kore.lab.pencroff.com/examples/outcome/): Mapping, piping, combinators, error handling
- [Logger examples](https://kore.lab.pencroff.com/examples/logger/): Log levels, transports, child loggers
- [dtStamp examples](https://kore.lab.pencroff.com/examples/format_dt/): Date formatting options
- [Examples index](https://kore.lab.pencroff.com/examples/)

## Guides

- [Flow operation flows](https://kore.lab.pencroff.com/guides/flow-operation-flows/): Creating results, exception boundaries, transformations, pipelines, combinators, terminal operations, serialization, input protection
- [Error handling patterns](https://kore.lab.pencroff.com/guides/error-handling-patterns/): Err composition, propagation, the nominal type guard, real-world scenarios
- [Migration from throwing](https://kore.lab.pencroff.com/guides/migration-from-throwing/): Step-by-step try/catch to result tuple conversion

## Optional

- [Documentation guide](https://kore.lab.pencroff.com/guides/docs_guide/): Documentation layers model and budget rules
- [TSDoc guide](https://kore.lab.pencroff.com/guides/tsdoc_guide/): Formatting rules for source comments
- [Changelog](https://kore.lab.pencroff.com/changelog/)

## Quick Start

```typescript
import { Err, ok, fail, pipe, onOk, onErr, defaultTo } from "@pencroff-lab/kore";
import { dtStamp, log, createLogger } from "@pencroff-lab/kore";
import { expectOk, expectErr } from "@pencroff-lab/kore/test";
```

## Install

```bash
npm install @pencroff-lab/kore
```