ts-data-forge 6.13.0 → 6.13.1

package/dist/functional/pipe.d.mts

@@ -1,4 +1,3 @@
-import { type MergeIntersection } from 'ts-type-forge';
 import { Optional, type UnknownOptional } from './optional/index.mjs';
 /**
  * Creates a new pipe object that allows for chaining operations on a value.
@@ -18,15 +17,8 @@ import { Optional, type UnknownOptional } from './optional/index.mjs';
  * @param a The initial value to wrap in a pipe.
  * @returns A pipe object with chaining methods appropriate for the value type.
  */
-export declare function pipe<const A extends UnknownOptional>(a: A): PipeWithMapOptional<A>;
-export declare function pipe<const A>(a: A): PipeBase<A>;
-type Pipe<A> = A extends UnknownOptional ? PipeWithMapOptional<A> : PipeBase<A>;
-/**
- * @template A The type of the current value in the pipe.
- * @internal
- * Base pipe interface providing core functionality.
- * All pipe types extend this interface.
- */
+export declare const pipe: <const A>(a: A) => Pipe<A>;
+export type Pipe<A> = PipeBase<A> & PipeMapNullable<A> & ([A] extends [UnknownOptional] ? PipeMapOptional<A> : unknown);
 type PipeBase<A> = Readonly<{
     /** The current value being piped. */
     value: A;
@@ -48,6 +40,8 @@ type PipeBase<A> = Readonly<{
      * @returns A new pipe containing the transformed value.
      */
     map: <B>(fn: (a: A) => B) => Pipe<B>;
+}>;
+type PipeMapNullable<A> = Readonly<{
     /**
      * Maps the current value only if it's not null or undefined. If the current
      * value is null/undefined, the transformation is skipped and undefined is
@@ -75,13 +69,7 @@ type PipeBase<A> = Readonly<{
      */
     mapNullable: <B>(fn: (a: NonNullable<A>) => B) => Pipe<B | undefined>;
 }>;
-/**
- * @template A The Optional type currently in the pipe.
- * @internal
- * Pipe interface for Optional values, providing Optional-aware mapping.
- * Extends PipeBase with mapOptional functionality for monadic operations.
- */
-type PipeWithMapOptional<A extends UnknownOptional> = MergeIntersection<PipeBase<A> & Readonly<{
+type PipeMapOptional<A extends UnknownOptional> = Readonly<{
     /**
      * Maps the value inside an Optional using Optional.map semantics. If the
      * Optional is None, the transformation is skipped and None is propagated.
@@ -109,6 +97,6 @@ type PipeWithMapOptional<A extends UnknownOptional> = MergeIntersection<PipeBase
      * @returns A new pipe containing an Optional with the transformed value.
      */
     mapOptional: <B>(fn: (a: Optional.Unwrap<A>) => B) => Pipe<Optional<B>>;
-}>>;
+}>;
 export {};
 //# sourceMappingURL=pipe.d.mts.map

package/dist/functional/pipe.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"pipe.d.mts","sourceRoot":"","sources":["../../src/functional/pipe.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,eAAe,EAClD,CAAC,EAAE,CAAC,GACH,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE1B,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAkBjD,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,eAAe,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,KAAK,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC1B,qCAAqC;IACrC,KAAK,EAAE,CAAC,CAAC;IAET;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACvE,CAAC,CAAC;AAEH;;;;;GAKG;AACH,KAAK,mBAAmB,CAAC,CAAC,SAAS,eAAe,IAAI,iBAAiB,CACrE,QAAQ,CAAC,CAAC,CAAC,GACT,QAAQ,CAAC;IACP;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,CACL,CAAC"}
+{"version":3,"file":"pipe.d.mts","sourceRoot":"","sources":["../../src/functional/pipe.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,CAAC,CAAC,EAAG,GAAG,CAAC,KAAG,IAAI,CAAC,CAAC,CAYI,CAAC;AAmBjD,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAC/B,eAAe,CAAC,CAAC,CAAC,GAClB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;AAgCjE,KAAK,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC1B,qCAAqC;IACrC,KAAK,EAAE,CAAC,CAAC;IAET;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;CACtC,CAAC,CAAC;AAEH,KAAK,eAAe,CAAC,CAAC,IAAI,QAAQ,CAAC;IACjC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACvE,CAAC,CAAC;AAEH,KAAK,eAAe,CAAC,CAAC,SAAS,eAAe,IAAI,QAAQ,CAAC;IACzD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,CAAC"}

package/dist/functional/pipe.mjs

@@ -1,22 +1,42 @@
 import { isOptional } from './optional/impl/optional-is-optional.mjs';
 import { map } from './optional/impl/optional-map.mjs';
 
-function pipe(a) {
-    if (isOptional(a)) {
-        return {
-            value: a,
-            map: (fn) => pipe(fn(a)),
+/**
+ * Creates a new pipe object that allows for chaining operations on a value.
+ *
+ * This function provides a fluent interface for applying transformations to
+ * values, with intelligent method selection based on the input type:
+ *
+ * - For `Optional` values: Provides `mapOptional` for safe Optional
+ *   transformations
+ * - For other values: Provides `mapNullable` for null-safe transformations
+ * - All types get the basic `map` method for general transformations
+ *
+ * The pipe maintains type safety throughout the chain, automatically selecting
+ * the appropriate overload based on the current value type.
+ *
+ * @template A The type of the initial value to wrap in a pipe.
+ * @param a The initial value to wrap in a pipe.
+ * @returns A pipe object with chaining methods appropriate for the value type.
+ */
+const pipe = (a) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+({
+    value: a,
+    map: (fn) => pipe(fn(a)),
+    mapNullable: (fn) => pipe(a == null ? undefined : fn(a)),
+    ...(isOptional(a)
+        ? {
             mapOptional: (fn) => pipe(map(a, fn)),
-        };
-    }
-    else {
-        return {
-            value: a,
-            map: (fn) => pipe(fn(a)),
-            mapNullable: (fn) => pipe(a == null ? undefined : fn(a)),
-        };
-    }
-}
+        }
+        : {}),
+});
+// NOTE: 以下では 'typing when used with generics' test で型エラーが出る。
+// 詳細は documents/reports/pipe-typing.md の 「mapNullable を条件付きで含めるのがうまくいかない理由」を参照。
+// export type Pipe<A> = PipeBase<A> &
+//   ([A] extends [UnknownOptional] ? PipeMapOptional<A> : unknown) &
+//   ([undefined] extends [A] ? PipeMapNullable<A> : unknown) &
+//   ([null] extends [A] ? PipeMapNullable<A> : unknown);
 
 export { pipe };
 //# sourceMappingURL=pipe.mjs.map

package/dist/functional/pipe.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pipe.mjs","sources":["../../src/functional/pipe.mts"],"sourcesContent":[null],"names":["Optional.isOptional","Optional.map"],"mappings":";;;AA2BM,SAAU,IAAI,CAAU,CAAI,EAAA;AAChC,IAAA,IAAIA,UAAmB,CAAC,CAAC,CAAC,EAAE;QAC1B,OAAO;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACxB,YAAA,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAACC,GAAY,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;SAC/C;IACH;SAAO;QACL,OAAO;AACL,YAAA,KAAK,EAAE,CAAC;AACR,YAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACxB,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,GAAG,SAAS,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;SACzD;IACH;AACF;;;;"}
+{"version":3,"file":"pipe.mjs","sources":["../../src/functional/pipe.mts"],"sourcesContent":[null],"names":["Optional.isOptional","Optional.map"],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;AAiBG;AACI,MAAM,IAAI,GAAG,CAAW,CAAI;AACjC;AACA,CAAC;AACC,IAAA,KAAK,EAAE,CAAC;AACR,IAAA,GAAG,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxB,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,GAAG,SAAS,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAExD,IAAA,IAAIA,UAAmB,CAAC,CAAC;AACvB,UAAE;AACE,YAAA,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAACC,GAAY,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C;UACD,EAAE,CAAC;AACR,CAAA;AAuBH;AACA;AACA;AACA;AACA;AACA;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "6.13.0",
+  "version": "6.13.1",
   "private": false,
   "keywords": [
     "typescript",
@@ -42,6 +42,9 @@
     "clean": "pnpm run /clean:.*/",
     "clean:logs": "npx rimraf ./*.log",
     "codemod": "run-s codemod:uncommitted:as-const fmt codemod:uncommitted:readonly fmt",
+    "codemod:diff": "run-s codemod:diff:as-const fmt codemod:diff:readonly fmt",
+    "codemod:diff:as-const": "append-as-const --diff-from origin/main '{src,scripts,samples,test}/**/*.{mts,tsx}'",
+    "codemod:diff:readonly": "convert-to-readonly --diff-from origin/main '{src,scripts,samples,test}/**/*.{mts,tsx}'",
     "codemod:full": "run-s codemod:full:as-const fmt codemod:full:readonly fmt",
     "codemod:full:as-const": "append-as-const '{src,scripts,samples,test}/**/*.{mts,tsx}'",
     "codemod:full:readonly": "convert-to-readonly '{src,scripts,samples,test}/**/*.{mts,tsx}'",

package/src/functional/pipe.mts

@@ -1,4 +1,4 @@
-import { type MergeIntersection } from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
 import { Optional, type UnknownOptional } from './optional/index.mjs';
 
 /**
@@ -19,36 +19,71 @@ import { Optional, type UnknownOptional } from './optional/index.mjs';
  * @param a The initial value to wrap in a pipe.
  * @returns A pipe object with chaining methods appropriate for the value type.
  */
-export function pipe<const A extends UnknownOptional>(
-  a: A,
-): PipeWithMapOptional<A>;
-
-export function pipe<const A>(a: A): PipeBase<A>;
-
-export function pipe<const A>(a: A): PipeImpl<A> {
-  if (Optional.isOptional(a)) {
-    return {
-      value: a,
-      map: (fn) => pipe(fn(a)),
-      mapOptional: (fn) => pipe(Optional.map(a, fn)),
-    };
-  } else {
-    return {
-      value: a,
-      map: (fn) => pipe(fn(a)),
-      mapNullable: (fn) => pipe(a == null ? undefined : fn(a)),
-    };
-  }
-}
-
-type Pipe<A> = A extends UnknownOptional ? PipeWithMapOptional<A> : PipeBase<A>;
+export const pipe = <const A,>(a: A): Pipe<A> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  ({
+    value: a,
+    map: (fn) => pipe(fn(a)),
+    mapNullable: (fn) => pipe(a == null ? undefined : fn(a)),
+
+    ...(Optional.isOptional(a)
+      ? {
+          mapOptional: (fn) => pipe(Optional.map(a, fn)),
+        }
+      : {}),
+  }) satisfies PipeImpl<A> as unknown as Pipe<A>;
+
+// `PipeBase<A>` is always present; the conditional only *adds* `mapOptional`
+// for Optional values. Two subtleties motivate this shape:
+//
+//   1. The check is `[A] extends [UnknownOptional]` (a 1-tuple), not the bare
+//      `A extends UnknownOptional`. A bare check distributes over unions, so a
+//      piped union value such as `Result<D, E> | undefined` would expand into
+//      `Pipe<Ok<D>> | Pipe<Err<E>> | Pipe<undefined>`. Calling a chained method
+//      on that union of pipe objects forces TypeScript to synthesize a merged
+//      call signature, during which a branded member like `Ok<D>` is widened to
+//      its constraint (`Ok<number>`) — losing the brand `D`.
+//
+//   2. `value: A` lives on `PipeBase<A>`, *outside* the conditional. If `value`
+//      flowed through the conditional, then for a not-yet-resolved generic `A`
+//      the deferred true branch narrows `A` to `A & UnknownOptional`, so
+//      `.value` would surface as the noisy `(A & UnknownOptional) | A`. Keeping
+//      it on the unconditional base yields a clean `A`.
+// transformer-ignore-next-line convert-to-readonly
+export type Pipe<A> = PipeBase<A> &
+  PipeMapNullable<A> &
+  ([A] extends [UnknownOptional] ? PipeMapOptional<A> : unknown);
+
+// NOTE: 以下では 'typing when used with generics' test で型エラーが出る。
+// 詳細は documents/reports/pipe-typing.md の 「mapNullable を条件付きで含めるのがうまくいかない理由」を参照。
+// export type Pipe<A> = PipeBase<A> &
+//   ([A] extends [UnknownOptional] ? PipeMapOptional<A> : unknown) &
+//   ([undefined] extends [A] ? PipeMapNullable<A> : unknown) &
+//   ([null] extends [A] ? PipeMapNullable<A> : unknown);
+
+expectType<Optional<number>, UnknownOptional>('<=');
+
+expectType<number | undefined, undefined>('>=');
+
+expectType<keyof Pipe<number | undefined>, 'value' | 'map' | 'mapNullable'>(
+  '=',
+);
+
+expectType<
+  keyof Pipe<Optional<number>>,
+  'value' | 'map' | 'mapNullable' | 'mapOptional'
+>('=');
+
+expectType<
+  keyof Pipe<Optional<number | undefined>>,
+  'value' | 'map' | 'mapNullable' | 'mapOptional'
+>('=');
+
+expectType<
+  keyof Pipe<Optional<number> | undefined>,
+  'value' | 'map' | 'mapNullable'
+>('=');
 
-/**
- * @template A The type of the current value in the pipe.
- * @internal
- * Base pipe interface providing core functionality.
- * All pipe types extend this interface.
- */
 type PipeBase<A> = Readonly<{
   /** The current value being piped. */
   value: A;
@@ -71,7 +106,9 @@ type PipeBase<A> = Readonly<{
    * @returns A new pipe containing the transformed value.
    */
   map: <B>(fn: (a: A) => B) => Pipe<B>;
+}>;
 
+type PipeMapNullable<A> = Readonly<{
   /**
    * Maps the current value only if it's not null or undefined. If the current
    * value is null/undefined, the transformation is skipped and undefined is
@@ -100,56 +137,45 @@ type PipeBase<A> = Readonly<{
   mapNullable: <B>(fn: (a: NonNullable<A>) => B) => Pipe<B | undefined>;
 }>;
 
-/**
- * @template A The Optional type currently in the pipe.
- * @internal
- * Pipe interface for Optional values, providing Optional-aware mapping.
- * Extends PipeBase with mapOptional functionality for monadic operations.
- */
-type PipeWithMapOptional<A extends UnknownOptional> = MergeIntersection<
-  PipeBase<A> &
-    Readonly<{
-      /**
-       * Maps the value inside an Optional using Optional.map semantics. If the
-       * Optional is None, the transformation is skipped and None is propagated.
-       * If the Optional is Some, the transformation is applied to the inner
-       * value.
-       *
-       * @example
-       *
-       * ```ts
-       * const result = pipe(Optional.some(10))
-       *   .mapOptional((value) => value * 2)
-       *   .mapOptional((value) => value + 5);
-       *
-       * assert.deepStrictEqual(result.value, Optional.some(25));
-       *
-       * const empty = pipe(Optional.none as Optional<number>).mapOptional(
-       *   (value) => value * 2,
-       * );
-       *
-       * assert.isTrue(Optional.isNone(empty.value));
-       * ```
-       *
-       * @template B The type of the transformed inner value.
-       * @param fn Function to transform the inner value of the Optional.
-       * @returns A new pipe containing an Optional with the transformed value.
-       */
-      mapOptional: <B>(fn: (a: Optional.Unwrap<A>) => B) => Pipe<Optional<B>>;
-    }>
->;
+type PipeMapOptional<A extends UnknownOptional> = Readonly<{
+  /**
+   * Maps the value inside an Optional using Optional.map semantics. If the
+   * Optional is None, the transformation is skipped and None is propagated.
+   * If the Optional is Some, the transformation is applied to the inner
+   * value.
+   *
+   * @example
+   *
+   * ```ts
+   * const result = pipe(Optional.some(10))
+   *   .mapOptional((value) => value * 2)
+   *   .mapOptional((value) => value + 5);
+   *
+   * assert.deepStrictEqual(result.value, Optional.some(25));
+   *
+   * const empty = pipe(Optional.none as Optional<number>).mapOptional(
+   *   (value) => value * 2,
+   * );
+   *
+   * assert.isTrue(Optional.isNone(empty.value));
+   * ```
+   *
+   * @template B The type of the transformed inner value.
+   * @param fn Function to transform the inner value of the Optional.
+   * @returns A new pipe containing an Optional with the transformed value.
+   */
+  mapOptional: <B>(fn: (a: Optional.Unwrap<A>) => B) => Pipe<Optional<B>>;
+}>;
 
 /** @internal */
 type Cast<T, U> = T & U;
 
 /** @internal */
-type PipeImpl<A> = Partial<
-  Readonly<{
-    value: A;
-    map: <B>(fn: (a: A) => B) => PipeBase<B>;
-    mapNullable: <B>(fn: (a: NonNullable<A>) => B) => PipeBase<B | undefined>;
-    mapOptional: <B>(
-      fn: (a: Optional.Unwrap<Cast<A, UnknownOptional>>) => B,
-    ) => PipeBase<Optional<B>>;
-  }>
->;
+type PipeImpl<A> = Readonly<{
+  value: A;
+  map: <B>(fn: (a: A) => B) => PipeImpl<B>;
+  mapNullable?: <B>(fn: (a: NonNullable<A>) => B) => PipeImpl<B | undefined>;
+  mapOptional?: <B>(
+    fn: (a: Optional.Unwrap<Cast<A, UnknownOptional>>) => B,
+  ) => PipeImpl<Optional<B>>;
+}>;

package/src/functional/pipe.test.mts

@@ -2,6 +2,7 @@ import { expectType } from '../expect-type.mjs';
 import { type None, type Some } from '../types.mjs';
 import { Optional } from './optional/index.mjs';
 import { pipe } from './pipe.mjs';
+import { Result } from './result/index.mjs';
 
 describe(pipe, () => {
   test('basic pipe operations', () => {
@@ -35,7 +36,9 @@ describe(pipe, () => {
   });
 
   test('mapNullable with non-null value', () => {
-    const result = pipe(5 as number | null).mapNullable((x) => x * 2).value;
+    const s = 5 as number | null;
+
+    const result = pipe(s).mapNullable((x) => x * 2).value;
 
     expect(result).toBe(10);
 
@@ -95,4 +98,57 @@ describe(pipe, () => {
 
     expectType<typeof result, string>('=');
   });
+
+  test('typing when used with Result', () => {
+    const validate = <D,>(_u: unknown): Result<D, unknown> =>
+      Result.err(undefined);
+
+    const decodeBranded = (
+      input: string,
+      parse: (s: string) => number | undefined,
+    ): number | undefined => {
+      const v = pipe(input)
+        .map(parse)
+        .mapNullable(validate<number>)
+        .mapNullable((res) => Result.unwrapOk(res)).value;
+
+      expectType<typeof v, number | undefined>('=');
+
+      return v;
+    };
+
+    expect(decodeBranded('', () => undefined)).toBeUndefined();
+  });
+
+  test('typing when used with generics', () => {
+    const validate = <D,>(_u: unknown): Result<D, unknown> =>
+      Result.err(undefined);
+
+    // Regression: a generic brand `D` must survive the whole chain.
+    //
+    // The trigger is a `.map` whose result is a branded *union* such as
+    // `D | undefined`. If `Pipe<A>` distributes over unions, that step expands
+    // into `Pipe<D> | Pipe<undefined>`; calling the next method on the union of
+    // pipe objects then widens `D` to its constraint `number`, so `.value`
+    // collapses to `number | undefined` instead of `D | undefined`.
+    //
+    // The explicit `D | undefined` return annotation is itself the assertion:
+    // were the brand lost, `.value` would be `number | undefined` and the
+    // body would fail to compile.
+    const decodeBranded = <D extends number>(
+      input: string,
+      parse: (s: string) => D | undefined,
+    ): D | undefined => {
+      const v = pipe(input)
+        .map(parse)
+        .mapNullable((n) => validate<D>(n))
+        .mapNullable((res) => Result.unwrapOk(res)).value;
+
+      expectType<typeof v, D | undefined>('=');
+
+      return v;
+    };
+
+    expect(decodeBranded('', () => undefined)).toBeUndefined();
+  });
 });

package/src/others/map-nullable.test.mts

@@ -143,10 +143,9 @@ describe(mapNullable, () => {
 
       const toUpperCase = mapNullable((s: string) => s.toUpperCase());
 
-      const result = pipe(42 as number | null)
-        .map(toStr)
-        .map(addPrefix)
-        .map(toUpperCase).value;
+      const x = 42 as number | null;
+
+      const result = pipe(x).map(toStr).map(addPrefix).map(toUpperCase).value;
 
       expect(result).toBe('NUMBER: 42');
     });