🚀 Release 0.2.0

The example-code removal stripped the synopsis and examples with the
template modules; track bringing them back around the real API, with the
previous section order recorded so its placement is not re-guessed.

CHANGELOG.md

@@ -7,8 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-16
+
 - allow ternaries and lowercase comments in oxlint
 - switch `src/primitive.ts` prose from block comments to line comments
+- remove the template's `match`/`P` example modules and their documentation, and point `src/index.ts` at the primitive matchers
 
 ## [0.1.8] - 2026-09-16
 
@@ -51,7 +54,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - basic setup
 
-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...main
+[0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
 [0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
 [0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
 [0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6

README.md

@@ -2,34 +2,14 @@
 
 Pattern matching for TypeScript/ESM environments (F#-style, not regex).
 
-## Synopsis
-
-```ts
-import { match, P } from "tiny-pattern-ts";
-
-const reply = (answer: "yes" | "no") =>
-    match(answer)
-        .with(P.literal("yes"), (): "agreed" => "agreed")
-        .with(P.literal("no"), (): "declined" => "declined")
-        .exhaustive();
-
-reply("yes"); // "agreed"
-```
-
 ## Description
 
-`tiny-pattern-ts` gives TypeScript the shape of F#-style pattern matching:
-a value flows through a chain of patterns, the first one that matches runs its
-handler, and the handler receives the value narrowed to that pattern's type. The
-"patterns" are ordinary objects whose `matches` method is a TypeScript type
-guard, so narrowing composes the way any other guard does.
-
-It is deliberately not a regex engine and not a macro. There is no transpiler
-and no DSL to learn: `match(value)` returns a builder, `.with(pattern, handler)`
-adds a case, and the chain ends in either `.exhaustive()` or `.otherwise(...)`.
-The type-level contract is the feature — see
-[development/library.md](./development/library.md) for the design decisions and
-the known limitations.
+`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
+ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
+composes the way any other guard does. It is deliberately not a regex engine and
+not a macro: there is no transpiler and no DSL to learn, and the type-level
+contract is the feature — see [development/library.md](./development/library.md)
+for the design decisions and the known limitations.
 
 ## Requirements
 
@@ -39,124 +19,6 @@ the known limitations.
   both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
 - The package is **ESM-only** (no CommonJS shim).
 
-## Examples
-
-### Literal matching and `exhaustive()`
-
-`.exhaustive()` returns the union of the handler return types and throws if no
-case matched. Annotate handler returns when you want literal types rather than
-`string`:
-
-```ts
-type Answer = "yes" | "no";
-
-const reply = (answer: Answer): "agreed" | "declined" =>
-    match(answer)
-        .with(P.literal("yes"), (): "agreed" => "agreed")
-        .with(P.literal("no"), (): "declined" => "declined")
-        .exhaustive();
-
-reply("yes"); // "agreed"
-```
-
-`exhaustive()` checks at runtime, not at compile time — TypeScript does not force
-every union member to have a case (see
-[development/library.md](./development/library.md#exhaustive-is-a-runtime-check)).
-Use `.otherwise(...)` when a fallback is wanted:
-
-```ts
-const label = (answer: Answer): string =>
-    match(answer)
-        .with(P.literal("yes"), () => "agreed")
-        .otherwise(() => "not agreed");
-```
-
-### Matching by `typeof`
-
-`P.type<T>(name)` pairs an explicit type `T` with the runtime `typeof` name it
-should test for:
-
-```ts
-const describe = (value: unknown): string =>
-    match(value)
-        .with(P.type<string>("string"), (s) => `string of length ${s.length}`)
-        .with(P.type<number>("number"), (n) => `number ${n.toFixed(2)}`)
-        .otherwise(() => "something else");
-```
-
-The supported names are `string`, `number`, `boolean`, `bigint`, `symbol`,
-`undefined`, `object`, and `function`. `"object"` matches non-null objects and
-functions; `"undefined"` compares against `undefined` directly.
-
-### Structural matching and discriminated unions
-
-`P.shape(shape, refine?)` checks that every key in `shape` exists on the value.
-A value that is itself a matcher is applied, otherwise it is compared with
-strict equality. To narrow to a concrete type, pass a `refine` type guard:
-
-```ts
-interface Circle {
-    readonly kind: "circle";
-    readonly radius: number;
-}
-
-interface Square {
-    readonly kind: "square";
-    readonly side: number;
-}
-
-type Shape = Circle | Square;
-
-const area = (shape: Shape): number =>
-    match(shape)
-        .with(
-            P.shape({ kind: "circle" }, (v): v is Circle => "radius" in v),
-            (c) => Math.PI * c.radius ** 2,
-        )
-        .with(
-            P.shape({ kind: "square" }, (v): v is Square => "side" in v),
-            (s) => s.side ** 2,
-        )
-        .exhaustive();
-```
-
-Without `refine`, `P.shape` returns a matcher for the shape's own type, not the
-narrowed one. Nested matchers can be used in the shape object, for example
-`P.shape({ name: P.type<string>("string") })`.
-
-### Custom guards with `when`
-
-`P.when` takes a type guard and infers the narrowed type from it:
-
-```ts
-const toNumber = (value: unknown): number =>
-    match(value)
-        .with(
-            P.when((v): v is string => typeof v === "string"),
-            (s) => Number.parseInt(s, 10),
-        )
-        .otherwise(() => 0);
-```
-
-### Widening with `any`
-
-`P.any<T>(predicate)` takes a plain boolean predicate and a declared type `T`,
-for cases where the predicate cannot be written as a type guard:
-
-```ts
-const firstNumber = (items: readonly unknown[]): number | undefined =>
-    match(items)
-        .with(
-            P.any<readonly number[]>(
-                (v) =>
-                    Array.isArray(v) &&
-                    v.every((item) => typeof item === "number"),
-            ),
-            (xs) => xs[0],
-        )
-        .otherwise(() => undefined);
-```
-
 ## API
 
 Yet to be implemented

backlog.tasks

@@ -5,20 +5,26 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
 ---
 
 Setup:
-☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high
+☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
 ✔ straighten oxc rules @done
     ✔ oxc forbids ternary => remove oxc rule @done
     ✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
     ✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
 
+✔ Remove example code files and its documentation and its exports from index.ts @high @done
+    ✔ remove src/match.ts and its documentation @high @done
+    ✔ remove src/pattern.ts and its documentation @high @done
+    ✔ remove src/index.test.ts and its documentation @high @done
+    ✔ exports from `src/index.ts` should only be the public API surface @done
+
+
 v1.0:
 ☐ API surface is stable and fully typed
     ☐ Finalize public exports in `src/index.ts`
     ☐ Document all exported types and functions
     ☐ Add JSDoc for public APIs
 ☐ Test coverage meets threshold
-    ☐ Achieve 100% branch coverage on `src/pattern.ts`
-    ☐ Achieve 100% branch coverage on `src/match.ts`
+    ☐ Achieve 100% branch coverage on `src/primitive.ts`
     ☐ Achieve 100% branch coverage on `src/index.ts`
 
 Bugs:
@@ -28,6 +34,9 @@ Enhancements:
 ☐ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium
 
 Documentation:
+☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
+    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
+    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
 ☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
 ☐ Write migration guide for users coming from discriminated unions

development/testing.md

@@ -27,8 +27,8 @@ before the implementation.
 
 - Runtime-first (classic red/green): it verifies the value, not the contract,
   and the contract is the product.
-- Testing the type only: it would not catch handler wiring, `exhaustive()`
-  throwing, or the `otherwise` fallback (see `src/index.test.ts`).
+- Testing the type only: it would not catch handler dispatch or the `_`
+  fallback (see `src/primitive.test.ts`).
 
 The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
@@ -66,7 +66,7 @@ separated by a blank line; an empty block drops its label.
 ## Known issues
 
 - The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
-  test files that use it (`src/index.test.ts`, `src/primitive.test.ts`) carry a
+  test files that use it (`src/primitive.test.ts`) carry a
   file-level `oxlint-disable
 typescript/no-floating-promises` with an explanatory comment. It is a known
   false positive, not a rule worth disabling project-wide (see

development/tooling.md

@@ -105,8 +105,8 @@ Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 #### Decision (2026-09)
 
 A type-aware rule that false-positives is silenced with a source-level
-`oxlint-disable` directive (see `src/pattern.ts`, `src/match.ts`,
-`src/index.test.ts`), not by turning the rule off in `.oxlintrc.json`.
+`oxlint-disable` directive (see `src/primitive.ts`,
+`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
 
 #### Why
 

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "tiny-pattern-ts",
-            "version": "0.1.8",
+            "version": "0.2.0",
             "license": "MIT",
             "dependencies": {
                 "type-fest": "^5.9.0"

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.1.8",
+    "version": "0.2.0",
     "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
     "keywords": [
         "adt",

src/index.test.ts

@@ -1,71 +0,0 @@
-/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-
-import { expectTypeOf } from "expect-type";
-
-import { type Matcher, P, match } from "./index.ts";
-
-test("match returns a builder", () => {
-    // Act
-    const builder = match("x");
-
-    // Assert
-    expectTypeOf(builder).toHaveProperty("with");
-    expectTypeOf(builder).toHaveProperty("exhaustive");
-    expectTypeOf(builder).toHaveProperty("otherwise");
-});
-
-test("P.literal narrows to its literal type", () => {
-    // Act
-    const matcher = P.literal("yes");
-
-    // Assert
-    expectTypeOf(matcher).toExtend<Matcher<"yes">>();
-    assert.equal(matcher.matches("yes"), true);
-    assert.equal(matcher.matches("no"), false);
-});
-
-test("P.type narrows to the typeof target", () => {
-    // Act
-    const matcher = P.type<string>("string");
-
-    // Assert
-    expectTypeOf(matcher).toExtend<Matcher<string>>();
-    assert.equal(matcher.matches("hi"), true);
-    assert.equal(matcher.matches(42), false);
-});
-
-test("exhaustive() returns the union of handler return types", () => {
-    // Act
-    const result = match<"a" | "b">("a")
-        .with(P.literal("a"), () => 1 as const)
-        .with(P.literal("b"), () => "two" as const)
-        .exhaustive();
-
-    // Assert
-    expectTypeOf(result).toEqualTypeOf<1 | "two">();
-    assert.equal(result, 1);
-});
-
-test("otherwise() falls back when no case matches", () => {
-    // Act
-    const result = match<"x" | "y" | "z">("z")
-        .with(P.literal("x"), (v): string => `got ${v}`)
-        .otherwise((v): string => `fallback ${v}`);
-
-    // Assert
-    assert.equal(result, "fallback z");
-});
-
-test("exhaustive throws when no case matches", () => {
-    // Assert
-    assert.throws(
-        () =>
-            match<"a" | "b" | "c">("c")
-                .with(P.literal("a"), () => "A")
-                .with(P.literal("b"), () => "B")
-                .exhaustive(),
-        /no matching case/,
-    );
-});

src/index.ts

@@ -1,2 +1,6 @@
-export { match, P } from "./match.ts";
-export type { Matcher, Pattern } from "./pattern.ts";
+export {
+    getPrimitiveUnionMatcher,
+    getPrimitiveUnionMatcherPartial,
+    getPrimitiveUnionMatcherPartialW,
+    getPrimitiveUnionMatcherW,
+} from "./primitive.ts";

src/match.ts

@@ -1,62 +0,0 @@
-import { P, type Matcher, type Pattern } from "./pattern.ts";
-
-type Cases<R> = readonly (readonly [Matcher<unknown>, (value: unknown) => R])[];
-
-interface MatchBuilder<T, R> {
-    with<U extends T, V>(
-        pattern: Matcher<U>,
-        handler: (value: U) => V,
-    ): MatchBuilder<T, R | V>;
-    exhaustive(): R;
-    otherwise(handler: (value: T) => R): R;
-}
-
-const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
-    const apply = (): R | undefined => {
-        for (const [matcher, handler] of cases) {
-            if (matcher.matches(value)) {
-                return handler(value);
-            }
-        }
-        return undefined;
-    };
-
-    const builder = {
-        with<U extends T, V>(
-            pattern: Matcher<U>,
-            handler: (value: U) => V,
-        ): MatchBuilder<T, R | V> {
-            const nextCases: Cases<R | V> = [
-                ...cases,
-                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-                [pattern, handler as (value: unknown) => R | V],
-            ];
-            return buildMatch(value, nextCases);
-        },
-        exhaustive(): R {
-            const result = apply();
-            if (result === undefined) {
-                throw new Error(
-                    "tiny-pattern-ts: match.exhaustive() called with no matching case",
-                );
-            }
-            return result;
-        },
-        otherwise(handler: (value: T) => R): R {
-            for (const [matcher, run] of cases) {
-                if (matcher.matches(value)) {
-                    return run(value);
-                }
-            }
-            return handler(value);
-        },
-    };
-
-    return builder;
-};
-
-export const match = <T>(value: T): MatchBuilder<T, never> =>
-    buildMatch<T, never>(value, []);
-
-export type { Matcher, Pattern };
-export { P };

src/pattern.ts

@@ -1,105 +0,0 @@
-/**
- * Pattern matching primitives. Each constructor returns a lightweight
- * matcher object whose `matches` method returns a type guard.
- */
-
-export interface Matcher<T> {
-    readonly matches: (value: unknown) => value is T;
-}
-
-const literalMatcher = <
-    const L extends string | number | boolean | null | undefined,
->(
-    value: L,
-): Matcher<L> => ({
-    matches: (candidate): candidate is L => candidate === value,
-});
-const typeMatcher = <T>(
-        type:
-            | "string"
-            | "number"
-            | "boolean"
-            | "bigint"
-            | "symbol"
-            | "undefined"
-            | "object"
-            | "function",
-    ): Matcher<T> => {
-        const matches = (value: unknown): value is T => {
-            if (type === "undefined") {
-                return value === undefined;
-            }
-            if (type === "object") {
-                return (
-                    (typeof value === "object" && value !== null) ||
-                    typeof value === "function"
-                );
-            }
-            return typeof value === type;
-        };
-        return { matches };
-    },
-    whenMatcher = <T>(
-        predicate: (value: unknown) => value is T,
-    ): Matcher<T> => ({
-        matches: predicate,
-    }),
-    whenMatcherAny = <T>(
-        predicate: (value: unknown) => boolean,
-    ): Matcher<T> => ({
-        matches: (value: unknown): value is T => predicate(value),
-    }),
-    isNestedMatcher = (expected: unknown): expected is Matcher<unknown> =>
-        typeof expected === "object" &&
-        expected !== null &&
-        "matches" in expected,
-    // oxlint-disable-next-line typescript/no-unnecessary-type-parameters
-    keysMatch = <S extends object>(shape: S, candidate: object): boolean => {
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-        for (const key of Object.keys(shape) as (keyof S)[]) {
-            if (!(key in candidate)) {
-                return false;
-            }
-            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-            const expected = shape[key],
-                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-                actual = candidate[key as keyof object];
-            if (isNestedMatcher(expected)) {
-                if (!expected.matches(actual)) {
-                    return false;
-                }
-            } else if (actual !== expected) {
-                return false;
-            }
-        }
-        return true;
-    },
-    structuralMatcher = <S extends object, T extends S>(
-        shape: S,
-        refine?: (value: S) => value is T,
-    ): Matcher<T> => ({
-        matches: (value: unknown): value is T => {
-            if (typeof value !== "object" || value === null) {
-                return false;
-            }
-            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-            const candidate = value as S;
-            if (!keysMatch(shape, candidate)) {
-                return false;
-            }
-            if (refine && !refine(candidate)) {
-                return false;
-            }
-            return true;
-        },
-    });
-
-export const P = {
-    literal: literalMatcher,
-    type: typeMatcher,
-    when: whenMatcher,
-    any: whenMatcherAny,
-    shape: structuralMatcher,
-} as const;
-
-export type Pattern<T> = Matcher<T>;