@onrails/maybe 0.2.5 → 0.3.0

package/dist/maybe.d.ts

@@ -11,12 +11,37 @@
  * }
  * ```
  */
-export type Maybe<T> = {
+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";
@@ -54,6 +79,22 @@ export declare const of: typeof some;
  * ```
  */
 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`.
  *
@@ -153,8 +194,8 @@ export declare const match: {
     <T, U>(onSome: (value: T) => U, onNone: () => U): (maybe: Maybe<T>) => U;
 };
 export declare const unwrapOr: {
-    <T>(maybe: Maybe<T>, defaultValue: T): T;
-    <T>(defaultValue: T): (maybe: Maybe<T>) => T;
+    <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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/maybe",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Tagged Maybe for expected absence — pure tagged unions, Result interop, tree-shakeable",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -74,7 +74,7 @@
     }
   },
   "peerDependencies": {
-    "@onrails/result": "^0.4.0"
+    "@onrails/result": "^0.4.2"
   },
   "peerDependenciesMeta": {
     "@onrails/result": {
@@ -90,7 +90,7 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@onrails/result": "0.4.0",
+    "@onrails/result": "0.4.2",
     "fast-check": "^4.9.0",
     "ts-expect": "^1.3.0",
     "tsup": "^8.5.1"