# @pencroff-lab/kore

> Edition: v0.7.0
> Documentation for released version 0.7.0.
> Canonical URL: https://kore.lab.pencroff.com/v/0.7.0/

> 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/v/0.7.0/): entry point for all shipped documentation

## Core Modules

- [Err](https://kore.lab.pencroff.com/v/0.7.0/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/v/0.7.0/api/flow/): The primary API — free functions over `ResultTuple<T>` (`readonly [T, null] | readonly [null, Err]`): `ok`, `fail`, `attempt`/`attemptAsync`, `copy`, `map`/`flatMap`/`mapErr`/`effect` plus async forms, `ensure`, the `onOk`/`onErr`/`onTuple` stage factories, `pipe`/`pipeAsync` (typed through ten stages), `defaultTo` (handler-only), `either`, `all`, `any`, `fromJSON`. Every fallible callback returns a `ResultTuple`; the error slot is the only failure signal, and `map` is the one callback whose return is never inspected
- [flow test helpers](https://kore.lab.pencroff.com/v/0.7.0/api/test/): `expectOk` / `expectErr`, published from the `@pencroff-lab/kore/test` subpath only
- [Outcome](https://kore.lab.pencroff.com/v/0.7.0/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/v/0.7.0/api/logger/): Structured, level-filtered logging with pluggable transports and Err integration
- [dtStamp](https://kore.lab.pencroff.com/v/0.7.0/api/format_dt/): Compact, sortable date/time stamps for file names, log prefixes, and IDs
- [API overview](https://kore.lab.pencroff.com/v/0.7.0/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/v/0.7.0/examples/err/): Error creation, wrapping, codes, serialization
- [flow examples](https://kore.lab.pencroff.com/v/0.7.0/examples/flow/): Boundaries, the callback protocol, transformations, pipelines, collections, serialization, input protection
- [flow test helper examples](https://kore.lab.pencroff.com/v/0.7.0/examples/test/): Asserting on result tuples
- [Outcome examples](https://kore.lab.pencroff.com/v/0.7.0/examples/outcome/): Mapping, piping, combinators, error handling
- [Logger examples](https://kore.lab.pencroff.com/v/0.7.0/examples/logger/): Log levels, transports, child loggers
- [dtStamp examples](https://kore.lab.pencroff.com/v/0.7.0/examples/format_dt/): Date formatting options
- [Examples index](https://kore.lab.pencroff.com/v/0.7.0/examples/)

## Guides

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

## Optional

- [Documentation guide](https://kore.lab.pencroff.com/v/0.7.0/guides/docs_guide/): Documentation layers model and budget rules
- [TSDoc guide](https://kore.lab.pencroff.com/v/0.7.0/guides/tsdoc_guide/): Formatting rules for source comments
- [Changelog](https://kore.lab.pencroff.com/v/0.7.0/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
```