@onrails/maybe 0.2.3 → 0.3.0

package/dist/maybe.d.cts

@@ -0,0 +1,283 @@
+/**
+ * Tagged optional value — a discriminated union over `_tag` where absence
+ * (`None`) is an expected outcome, not a failure. Construct with {@link some} /
+ * {@link none}, narrow with {@link isSome} / {@link isNone}, and collapse with
+ * {@link match}.
+ *
+ * @example
+ * ```ts
+ * function findUser(id: string): Maybe<User> {
+ *   return fromNullable(db.users.get(id));
+ * }
+ * ```
+ */
+export type Maybe<T> = MaybeData<T> & MaybeMethods<T>;
+/**
+ * Plain-data shape of a {@link Maybe}: what `JSON.parse`, `structuredClone`
+ * and `postMessage` hand back. It has no methods; lift it with `Maybe.from`.
+ */
+export type MaybeData<T> = {
+    readonly _tag: "Some";
+    readonly value: T;
+} | {
+    readonly _tag: "None";
+};
+/**
+ * Methods every live {@link Maybe} carries on its (non-enumerable) prototype.
+ * Core semantics, mirroring `ResultMethods`: `tap` does not swallow throws.
+ */
+export interface MaybeMethods<T> {
+    /** Transform the `Some` value; `None` passes through. */
+    map<U>(fn: (value: T) => U): Maybe<U>;
+    /** Canonical bind; short-circuits on `None`. */
+    flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>;
+    /** Alias of {@link MaybeMethods.flatMap}. */
+    andThen<U>(fn: (value: T) => Maybe<U>): Maybe<U>;
+    /** Fold both branches into one value. */
+    match<U>(onSome: (value: T) => U, onNone: () => U): U;
+    /** The `Some` value, or `defaultValue` on `None`. */
+    unwrapOr<U>(defaultValue: U): T | U;
+    /** Observe the `Some` value, pass the maybe through. */
+    tap(fn: (value: T) => void): Maybe<T>;
+    /** Observe `None`, pass the maybe through. */
+    tapNone(fn: () => void): Maybe<T>;
+}
+/** The `Some` branch of a {@link Maybe} — a present value tagged `"Some"`. */
+export type Some<T> = Extract<Maybe<T>, {
+    _tag: "Some";
+}>;
+/** The `None` branch of a {@link Maybe} — expected absence, tagged `"None"`. */
+export type None = Extract<Maybe<never>, {
+    _tag: "None";
+}>;
+/**
+ * Lifts a value into the `Some` branch.
+ *
+ * @example
+ * ```ts
+ * const m = some(1);   // Maybe<number>
+ * ```
+ */
+export declare const some: <T>(value: T) => Maybe<T>;
+/**
+ * Fantasy Land `pure` — alias of {@link some}. One lift name shared across
+ * the trio (`of` / `Result.of` / `ResultAsync.of`) for generic and FL-style
+ * code.
+ *
+ * @example
+ * ```ts
+ * const m = of(1);   // Maybe<number> — identical to some(1)
+ * ```
+ */
+export declare const of: typeof some;
+/**
+ * The `None` value — represents expected absence. Not a failure.
+ *
+ * @example
+ * ```ts
+ * const cached: Maybe<User> = cache.has(id) ? some(cache.get(id)) : none();
+ * ```
+ */
+export declare const none: <T = never>() => Maybe<T>;
+/**
+ * Value-side companion of the {@link Maybe} type. `from` lifts plain data back
+ * into a live `Maybe` at every deserialization sink (`JSON.parse`,
+ * `structuredClone`, `postMessage`, Redux rehydration). It trusts the shape,
+ * but an unknown `_tag` is a defect and throws a `TypeError` rather than
+ * silently becoming `None`.
+ *
+ * @example
+ * ```ts
+ * const live = Maybe.from<number>(JSON.parse(JSON.stringify(some(1))));
+ * live.map((n) => n + 1);
+ * ```
+ */
+export declare const Maybe: {
+    readonly from: <T>(data: MaybeData<T>) => Maybe<T>;
+};
+/**
+ * Type-narrowing predicate: returns `true` when the value is `Some`.
+ *
+ * @example
+ * ```ts
+ * if (isSome(m)) {
+ *   console.log(m.value);   // narrowed to Some branch
+ * }
+ * ```
+ */
+export declare const isSome: <T>(maybe: Maybe<T>) => maybe is Some<T>;
+/**
+ * Type-narrowing predicate: returns `true` when the value is `None`.
+ *
+ * @example
+ * ```ts
+ * if (isNone(fromNullable(user))) {
+ *   return redirect("/login");   // narrowed to None branch
+ * }
+ * ```
+ */
+export declare const isNone: <T>(maybe: Maybe<T>) => maybe is None;
+/**
+ * Lift a nullable value into `Maybe<T>` — `null` and `undefined` become
+ * `None`; anything else becomes `Some`.
+ *
+ * @example
+ * ```ts
+ * fromNullable(cache.get(key));   // Maybe<V>
+ * fromNullable(null);             // None
+ * ```
+ */
+export declare const fromNullable: <T>(value: T | null | undefined) => Maybe<T>;
+/**
+ * Transform the `Some` value, passing `None` through unchanged. Dual-form.
+ *
+ * @example
+ * ```ts
+ * map(some(2), (n) => n * 3);                      // Some 6 — data-first
+ * pipe(fromNullable(input), map((s) => s.trim())); // curried
+ * ```
+ */
+export declare const map: {
+    <T, U>(maybe: Maybe<T>, fn: (value: T) => U): Maybe<U>;
+    <T, U>(fn: (value: T) => U): (maybe: Maybe<T>) => Maybe<U>;
+};
+/**
+ * Canonical bind for `Maybe`. Chains a `Maybe`-returning step;
+ * short-circuits on `None`. Dual-form.
+ *
+ * @example
+ * ```ts
+ * flatMap(fromNullable(user), (u) =>
+ *   u.active ? some(u) : none(),
+ * );
+ * ```
+ */
+export declare const flatMap: {
+    <T, U>(maybe: Maybe<T>, fn: (value: T) => Maybe<U>): Maybe<U>;
+    <T, U>(fn: (value: T) => Maybe<U>): (maybe: Maybe<T>) => Maybe<U>;
+};
+/**
+ * Neverthrow-compat alias of {@link flatMap} — same dual-form shape. Prefer
+ * {@link flatMap} as the canonical name; reach for `andThen` only when porting
+ * neverthrow code or matching its vocabulary.
+ *
+ * @example
+ * ```ts
+ * andThen(fromNullable(user), (u) =>
+ *   u.active ? some(u) : none(),
+ * );
+ * ```
+ */
+export declare const andThen: {
+    <T, U>(maybe: Maybe<T>, fn: (value: T) => Maybe<U>): Maybe<U>;
+    <T, U>(fn: (value: T) => Maybe<U>): (maybe: Maybe<T>) => Maybe<U>;
+};
+/**
+ * Terminal collapse — fold both branches into a single value. Positional,
+ * dual-form. Same shape as `Result.match` for sibling consistency.
+ *
+ * For files that also import `match` from `ts-pattern`, use a namespace
+ * import (`import * as Maybe from "@onrails/maybe"` → `Maybe.match`) to
+ * dissolve the collision.
+ *
+ * @example
+ * ```ts
+ * const greeting = match(
+ *   fromNullable(user),
+ *   (u) => `hello ${u.name}`,
+ *   () => "hello guest",
+ * );
+ * ```
+ */
+export declare const match: {
+    <T, U>(maybe: Maybe<T>, onSome: (value: T) => U, onNone: () => U): U;
+    <T, U>(onSome: (value: T) => U, onNone: () => U): (maybe: Maybe<T>) => U;
+};
+export declare const unwrapOr: {
+    <T, U>(maybe: Maybe<T>, defaultValue: U): T | U;
+    <U>(defaultValue: U): <T>(maybe: Maybe<T>) => T | U;
+};
+/**
+ * Unwraps the `Some` value or throws if the value is `None`.
+ *
+ * @throws when the value is None — assertion-tier; use {@link match} / {@link unwrapOr} in business logic.
+ * Allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.
+ *
+ * @example
+ * ```ts
+ * expect(unwrap(parseUser(raw))).toEqual(expected);
+ * ```
+ */
+export declare const unwrap: <T>(maybe: Maybe<T>) => T;
+/**
+ * Drop every `None` and collect the remaining `Some` values into an array.
+ *
+ * @example
+ * ```ts
+ * compact([some(1), none(), some(2)]);    // [1, 2]
+ * ```
+ */
+export declare const compact: <T>(maybes: readonly Maybe<T>[]) => T[];
+/**
+ * `compact(items.map(fn))` — map each item to `Maybe`, drop `None`,
+ * collect the rest.
+ *
+ * @example
+ * ```ts
+ * compactMap(rawRows, (row) =>
+ *   row.deletedAt ? none() : some(row.id),
+ * );
+ * // string[]
+ * ```
+ */
+export declare const compactMap: <T, U>(items: readonly T[], fn: (item: T) => Maybe<U>) => U[];
+/**
+ * `flatMap(fromNullable(value), fn)` — lift a nullable then bind through
+ * a `Maybe`-returning step. Convenient for chaining lookups.
+ *
+ * @example
+ * ```ts
+ * optional(rawId, (id) => fromNullable(cache.get(id)));
+ * ```
+ */
+export declare const optional: <T, U>(value: T | null | undefined, fn: (value: T) => Maybe<U>) => Maybe<U>;
+/**
+ * Run a side effect on the `Some` value, pass the `Maybe` through unchanged.
+ * `None` is a no-op. Mirrors `tap` from `@onrails/result`. Dual-form.
+ *
+ * @example
+ * ```ts
+ * tap(some(2), (n) => console.log(n));               // logs 2, returns Some 2
+ * pipe(fromNullable(row), tap((r) => sink.push(r))); // curried — collect on Some
+ * ```
+ */
+export declare const tap: {
+    <T>(maybe: Maybe<T>, fn: (value: T) => void): Maybe<T>;
+    <T>(fn: (value: T) => void): (maybe: Maybe<T>) => Maybe<T>;
+};
+/**
+ * Run a side effect when the `Maybe` is `None`, pass it through unchanged.
+ * `Some` is a no-op. The `None`-side mirror of {@link tap}. Dual-form.
+ *
+ * @example
+ * ```ts
+ * tapNone(none(), () => metrics.miss());              // runs effect, returns None
+ * pipe(fromNullable(hit), tapNone(() => metrics.miss())); // curried
+ * ```
+ */
+export declare const tapNone: {
+    <T>(maybe: Maybe<T>, fn: () => void): Maybe<T>;
+    <T>(fn: () => void): (maybe: Maybe<T>) => Maybe<T>;
+};
+/**
+ * Debug printer — renders a maybe as `Some(…)` / `None` for logs. Payloads
+ * print as JSON (values are plain data by design); non-JSON payloads fall
+ * back to `String(...)`. Mirror of the result package's `show`.
+ *
+ * @example
+ * ```ts
+ * show(some(1));   // 'Some(1)'
+ * show(none());    // 'None'
+ * ```
+ */
+export declare const show: <T>(maybe: Maybe<T>) => string;

package/dist/maybe.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Tagged optional value — a discriminated union over `_tag` where absence
+ * (`None`) is an expected outcome, not a failure. Construct with {@link some} /
+ * {@link none}, narrow with {@link isSome} / {@link isNone}, and collapse with
+ * {@link match}.
+ *
+ * @example
+ * ```ts
+ * function findUser(id: string): Maybe<User> {
+ *   return fromNullable(db.users.get(id));
+ * }
+ * ```
+ */
+export type Maybe<T> = MaybeData<T> & MaybeMethods<T>;
+/**
+ * Plain-data shape of a {@link Maybe}: what `JSON.parse`, `structuredClone`
+ * and `postMessage` hand back. It has no methods; lift it with `Maybe.from`.
+ */
+export type MaybeData<T> = {
+    readonly _tag: "Some";
+    readonly value: T;
+} | {
+    readonly _tag: "None";
+};
+/**
+ * Methods every live {@link Maybe} carries on its (non-enumerable) prototype.
+ * Core semantics, mirroring `ResultMethods`: `tap` does not swallow throws.
+ */
+export interface MaybeMethods<T> {
+    /** Transform the `Some` value; `None` passes through. */
+    map<U>(fn: (value: T) => U): Maybe<U>;
+    /** Canonical bind; short-circuits on `None`. */
+    flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>;
+    /** Alias of {@link MaybeMethods.flatMap}. */
+    andThen<U>(fn: (value: T) => Maybe<U>): Maybe<U>;
+    /** Fold both branches into one value. */
+    match<U>(onSome: (value: T) => U, onNone: () => U): U;
+    /** The `Some` value, or `defaultValue` on `None`. */
+    unwrapOr<U>(defaultValue: U): T | U;
+    /** Observe the `Some` value, pass the maybe through. */
+    tap(fn: (value: T) => void): Maybe<T>;
+    /** Observe `None`, pass the maybe through. */
+    tapNone(fn: () => void): Maybe<T>;
+}
+/** The `Some` branch of a {@link Maybe} — a present value tagged `"Some"`. */
+export type Some<T> = Extract<Maybe<T>, {
+    _tag: "Some";
+}>;
+/** The `None` branch of a {@link Maybe} — expected absence, tagged `"None"`. */
+export type None = Extract<Maybe<never>, {
+    _tag: "None";
+}>;
+/**
+ * Lifts a value into the `Some` branch.
+ *
+ * @example
+ * ```ts
+ * const m = some(1);   // Maybe<number>
+ * ```
+ */
+export declare const some: <T>(value: T) => Maybe<T>;
+/**
+ * Fantasy Land `pure` — alias of {@link some}. One lift name shared across
+ * the trio (`of` / `Result.of` / `ResultAsync.of`) for generic and FL-style
+ * code.
+ *
+ * @example
+ * ```ts
+ * const m = of(1);   // Maybe<number> — identical to some(1)
+ * ```
+ */
+export declare const of: typeof some;
+/**
+ * The `None` value — represents expected absence. Not a failure.
+ *
+ * @example
+ * ```ts
+ * const cached: Maybe<User> = cache.has(id) ? some(cache.get(id)) : none();
+ * ```
+ */
+export declare const none: <T = never>() => Maybe<T>;
+/**
+ * Value-side companion of the {@link Maybe} type. `from` lifts plain data back
+ * into a live `Maybe` at every deserialization sink (`JSON.parse`,
+ * `structuredClone`, `postMessage`, Redux rehydration). It trusts the shape,
+ * but an unknown `_tag` is a defect and throws a `TypeError` rather than
+ * silently becoming `None`.
+ *
+ * @example
+ * ```ts
+ * const live = Maybe.from<number>(JSON.parse(JSON.stringify(some(1))));
+ * live.map((n) => n + 1);
+ * ```
+ */
+export declare const Maybe: {
+    readonly from: <T>(data: MaybeData<T>) => Maybe<T>;
+};
+/**
+ * Type-narrowing predicate: returns `true` when the value is `Some`.
+ *
+ * @example
+ * ```ts
+ * if (isSome(m)) {
+ *   console.log(m.value);   // narrowed to Some branch
+ * }
+ * ```
+ */
+export declare const isSome: <T>(maybe: Maybe<T>) => maybe is Some<T>;
+/**
+ * Type-narrowing predicate: returns `true` when the value is `None`.
+ *
+ * @example
+ * ```ts
+ * if (isNone(fromNullable(user))) {
+ *   return redirect("/login");   // narrowed to None branch
+ * }
+ * ```
+ */
+export declare const isNone: <T>(maybe: Maybe<T>) => maybe is None;
+/**
+ * Lift a nullable value into `Maybe<T>` — `null` and `undefined` become
+ * `None`; anything else becomes `Some`.
+ *
+ * @example
+ * ```ts
+ * fromNullable(cache.get(key));   // Maybe<V>
+ * fromNullable(null);             // None
+ * ```
+ */
+export declare const fromNullable: <T>(value: T | null | undefined) => Maybe<T>;
+/**
+ * Transform the `Some` value, passing `None` through unchanged. Dual-form.
+ *
+ * @example
+ * ```ts
+ * map(some(2), (n) => n * 3);                      // Some 6 — data-first
+ * pipe(fromNullable(input), map((s) => s.trim())); // curried
+ * ```
+ */
+export declare const map: {
+    <T, U>(maybe: Maybe<T>, fn: (value: T) => U): Maybe<U>;
+    <T, U>(fn: (value: T) => U): (maybe: Maybe<T>) => Maybe<U>;
+};
+/**
+ * Canonical bind for `Maybe`. Chains a `Maybe`-returning step;
+ * short-circuits on `None`. Dual-form.
+ *
+ * @example
+ * ```ts
+ * flatMap(fromNullable(user), (u) =>
+ *   u.active ? some(u) : none(),
+ * );
+ * ```
+ */
+export declare const flatMap: {
+    <T, U>(maybe: Maybe<T>, fn: (value: T) => Maybe<U>): Maybe<U>;
+    <T, U>(fn: (value: T) => Maybe<U>): (maybe: Maybe<T>) => Maybe<U>;
+};
+/**
+ * Neverthrow-compat alias of {@link flatMap} — same dual-form shape. Prefer
+ * {@link flatMap} as the canonical name; reach for `andThen` only when porting
+ * neverthrow code or matching its vocabulary.
+ *
+ * @example
+ * ```ts
+ * andThen(fromNullable(user), (u) =>
+ *   u.active ? some(u) : none(),
+ * );
+ * ```
+ */
+export declare const andThen: {
+    <T, U>(maybe: Maybe<T>, fn: (value: T) => Maybe<U>): Maybe<U>;
+    <T, U>(fn: (value: T) => Maybe<U>): (maybe: Maybe<T>) => Maybe<U>;
+};
+/**
+ * Terminal collapse — fold both branches into a single value. Positional,
+ * dual-form. Same shape as `Result.match` for sibling consistency.
+ *
+ * For files that also import `match` from `ts-pattern`, use a namespace
+ * import (`import * as Maybe from "@onrails/maybe"` → `Maybe.match`) to
+ * dissolve the collision.
+ *
+ * @example
+ * ```ts
+ * const greeting = match(
+ *   fromNullable(user),
+ *   (u) => `hello ${u.name}`,
+ *   () => "hello guest",
+ * );
+ * ```
+ */
+export declare const match: {
+    <T, U>(maybe: Maybe<T>, onSome: (value: T) => U, onNone: () => U): U;
+    <T, U>(onSome: (value: T) => U, onNone: () => U): (maybe: Maybe<T>) => U;
+};
+export declare const unwrapOr: {
+    <T, U>(maybe: Maybe<T>, defaultValue: U): T | U;
+    <U>(defaultValue: U): <T>(maybe: Maybe<T>) => T | U;
+};
+/**
+ * Unwraps the `Some` value or throws if the value is `None`.
+ *
+ * @throws when the value is None — assertion-tier; use {@link match} / {@link unwrapOr} in business logic.
+ * Allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.
+ *
+ * @example
+ * ```ts
+ * expect(unwrap(parseUser(raw))).toEqual(expected);
+ * ```
+ */
+export declare const unwrap: <T>(maybe: Maybe<T>) => T;
+/**
+ * Drop every `None` and collect the remaining `Some` values into an array.
+ *
+ * @example
+ * ```ts
+ * compact([some(1), none(), some(2)]);    // [1, 2]
+ * ```
+ */
+export declare const compact: <T>(maybes: readonly Maybe<T>[]) => T[];
+/**
+ * `compact(items.map(fn))` — map each item to `Maybe`, drop `None`,
+ * collect the rest.
+ *
+ * @example
+ * ```ts
+ * compactMap(rawRows, (row) =>
+ *   row.deletedAt ? none() : some(row.id),
+ * );
+ * // string[]
+ * ```
+ */
+export declare const compactMap: <T, U>(items: readonly T[], fn: (item: T) => Maybe<U>) => U[];
+/**
+ * `flatMap(fromNullable(value), fn)` — lift a nullable then bind through
+ * a `Maybe`-returning step. Convenient for chaining lookups.
+ *
+ * @example
+ * ```ts
+ * optional(rawId, (id) => fromNullable(cache.get(id)));
+ * ```
+ */
+export declare const optional: <T, U>(value: T | null | undefined, fn: (value: T) => Maybe<U>) => Maybe<U>;
+/**
+ * Run a side effect on the `Some` value, pass the `Maybe` through unchanged.
+ * `None` is a no-op. Mirrors `tap` from `@onrails/result`. Dual-form.
+ *
+ * @example
+ * ```ts
+ * tap(some(2), (n) => console.log(n));               // logs 2, returns Some 2
+ * pipe(fromNullable(row), tap((r) => sink.push(r))); // curried — collect on Some
+ * ```
+ */
+export declare const tap: {
+    <T>(maybe: Maybe<T>, fn: (value: T) => void): Maybe<T>;
+    <T>(fn: (value: T) => void): (maybe: Maybe<T>) => Maybe<T>;
+};
+/**
+ * Run a side effect when the `Maybe` is `None`, pass it through unchanged.
+ * `Some` is a no-op. The `None`-side mirror of {@link tap}. Dual-form.
+ *
+ * @example
+ * ```ts
+ * tapNone(none(), () => metrics.miss());              // runs effect, returns None
+ * pipe(fromNullable(hit), tapNone(() => metrics.miss())); // curried
+ * ```
+ */
+export declare const tapNone: {
+    <T>(maybe: Maybe<T>, fn: () => void): Maybe<T>;
+    <T>(fn: () => void): (maybe: Maybe<T>) => Maybe<T>;
+};
+/**
+ * Debug printer — renders a maybe as `Some(…)` / `None` for logs. Payloads
+ * print as JSON (values are plain data by design); non-JSON payloads fall
+ * back to `String(...)`. Mirror of the result package's `show`.
+ *
+ * @example
+ * ```ts
+ * show(some(1));   // 'Some(1)'
+ * show(none());    // 'None'
+ * ```
+ */
+export declare const show: <T>(maybe: Maybe<T>) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/maybe",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Tagged Maybe for expected absence — pure tagged unions, Result interop, tree-shakeable",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -43,23 +43,38 @@
   ],
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./fluent": {
-      "types": "./dist/fluent.d.ts",
-      "import": "./dist/fluent.js",
-      "require": "./dist/fluent.cjs"
+      "import": {
+        "types": "./dist/fluent.d.ts",
+        "default": "./dist/fluent.js"
+      },
+      "require": {
+        "types": "./dist/fluent.d.cts",
+        "default": "./dist/fluent.cjs"
+      }
     },
     "./interop": {
-      "types": "./dist/interop.d.ts",
-      "import": "./dist/interop.js",
-      "require": "./dist/interop.cjs"
+      "import": {
+        "types": "./dist/interop.d.ts",
+        "default": "./dist/interop.js"
+      },
+      "require": {
+        "types": "./dist/interop.d.cts",
+        "default": "./dist/interop.cjs"
+      }
     }
   },
   "peerDependencies": {
-    "@onrails/result": "0.2.0"
+    "@onrails/result": "^0.4.2"
   },
   "peerDependenciesMeta": {
     "@onrails/result": {
@@ -70,13 +85,13 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "check": "bun typecheck && bun test",
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json && bun run ../../scripts/dts-to-cts.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@onrails/result": "0.2.0",
-    "fast-check": "^3.23.2",
+    "@onrails/result": "0.4.2",
+    "fast-check": "^4.9.0",
     "ts-expect": "^1.3.0",
     "tsup": "^8.5.1"
   }