@prisma-next/utils 0.11.0-dev.14 → 0.11.0-dev.15

package/dist/casts-D2-X_DNw.mjs

@@ -0,0 +1,82 @@
+//#region src/casts.ts
+/**
+* **Last-resort escape hatch for unsafe type assertions. Not a sanctioned tool to reach for.**
+*
+* Before reaching for `blindCast`, **rewrite the surrounding code so the cast becomes
+* unnecessary**: tighten an input type, add a runtime check that narrows via a type
+* predicate, restructure a generic so the compiler can see the relationship you're
+* asserting, or use {@link castAs} when the value already satisfies the target type.
+* Only when no rewrite is feasible does `blindCast` become the right answer — and at
+* that point, the `Reason` literal you supply must articulate the compromise in
+* language a reviewer can evaluate.
+*
+* The reviewer **will** validate the `Reason`. If it doesn't hold up under scrutiny,
+* that is not a signal to soften the reason; it is a signal to go back and solve the
+* underlying type-system problem properly. An unconvincing justification is rework,
+* not a free pass.
+*
+* `blindCast` is the auditable form of `as Foo` / `as unknown as Foo`: it bypasses
+* the compiler's checks (the input type is `unknown`, the output type is whatever the
+* caller asks for), but it forces the unsafety to be named at the call site instead of
+* smuggled in via a bare `as`. The `Reason` type parameter exists only at compile
+* time — it is not present in the emitted JavaScript — but it is grep-able and
+* visible to future readers.
+*
+* @example
+* ```typescript
+* const stringValue = blindCast<
+*   string,
+*   "JSON.parse returns `unknown`; this field is documented to be a string in the API contract"
+* >(parsed[key]);
+* ```
+*
+* @typeParam TargetType - The type the caller is asserting the input has.
+* @typeParam _Reason - A string literal describing why bypassing the type system is necessary here.
+*                     Only meaningful at compile time. The reviewer evaluates whether it justifies the unsafety.
+*/
+function blindCast(input) {
+	return input;
+}
+/**
+* Type-checked, runtime pass-through alternative to a bare `as Type` cast.
+*
+* Use `castAs` when the value already satisfies the target type but you want to make
+* the type assertion explicit at the call site — for example, when an inferred type is
+* wider than the type you want to publish, or when a literal object should be tagged
+* with its nominal interface. Unlike {@link blindCast}, the compiler still checks that
+* the value is assignable to the target type, so this helper cannot smuggle in an
+* unsafe assertion.
+*
+* `castAs` exists alongside `blindCast` so authors pick the right name at the call
+* site: a `castAs` is type-checked and benign; a `blindCast` is the unsafe escape
+* hatch. The split makes review faster — readers know which casts to scrutinize and
+* which are pure annotations.
+*
+* @example
+* ```typescript
+* interface FancyObject {
+*   key: string;
+*   keyTwo: {
+*     subKey: string;
+*     subKeyTwo: number;
+*   };
+* }
+*
+* const typedObject = castAs<FancyObject>({
+*   key: 'Chookede',
+*   keyTwo: {
+*     subKey: 'Choookeeeee',
+*     subKeyTwo: 2,
+*   },
+* });
+* ```
+*
+* @typeParam Type - The type to constrain and tag the value with. The value must be assignable to `Type`.
+*/
+function castAs(value) {
+	return value;
+}
+//#endregion
+export { castAs as n, blindCast as t };
+
+//# sourceMappingURL=casts-D2-X_DNw.mjs.map

package/dist/casts-D2-X_DNw.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"casts-D2-X_DNw.mjs","names":["x"],"sources":["../src/casts.ts"],"sourcesContent":["/**\n * **Last-resort escape hatch for unsafe type assertions. Not a sanctioned tool to reach for.**\n *\n * Before reaching for `blindCast`, **rewrite the surrounding code so the cast becomes\n * unnecessary**: tighten an input type, add a runtime check that narrows via a type\n * predicate, restructure a generic so the compiler can see the relationship you're\n * asserting, or use {@link castAs} when the value already satisfies the target type.\n * Only when no rewrite is feasible does `blindCast` become the right answer — and at\n * that point, the `Reason` literal you supply must articulate the compromise in\n * language a reviewer can evaluate.\n *\n * The reviewer **will** validate the `Reason`. If it doesn't hold up under scrutiny,\n * that is not a signal to soften the reason; it is a signal to go back and solve the\n * underlying type-system problem properly. An unconvincing justification is rework,\n * not a free pass.\n *\n * `blindCast` is the auditable form of `as Foo` / `as unknown as Foo`: it bypasses\n * the compiler's checks (the input type is `unknown`, the output type is whatever the\n * caller asks for), but it forces the unsafety to be named at the call site instead of\n * smuggled in via a bare `as`. The `Reason` type parameter exists only at compile\n * time — it is not present in the emitted JavaScript — but it is grep-able and\n * visible to future readers.\n *\n * @example\n * ```typescript\n * const stringValue = blindCast<\n *   string,\n *   \"JSON.parse returns `unknown`; this field is documented to be a string in the API contract\"\n * >(parsed[key]);\n * ```\n *\n * @typeParam TargetType - The type the caller is asserting the input has.\n * @typeParam _Reason - A string literal describing why bypassing the type system is necessary here.\n *                     Only meaningful at compile time. The reviewer evaluates whether it justifies the unsafety.\n */\nexport function blindCast<TargetType, _Reason extends string>(input: unknown): TargetType {\n  // biome-ignore lint/suspicious/noExplicitAny: this helper is the single canonical escape hatch for type-unsafe casts in the codebase; the `any` is hyper-local, the unsafety is made explicit at every call site via the call's own `Reason` literal, and the reviewer evaluates whether that justification holds\n  const x: any = input;\n  return x;\n}\n\n/**\n * Type-checked, runtime pass-through alternative to a bare `as Type` cast.\n *\n * Use `castAs` when the value already satisfies the target type but you want to make\n * the type assertion explicit at the call site — for example, when an inferred type is\n * wider than the type you want to publish, or when a literal object should be tagged\n * with its nominal interface. Unlike {@link blindCast}, the compiler still checks that\n * the value is assignable to the target type, so this helper cannot smuggle in an\n * unsafe assertion.\n *\n * `castAs` exists alongside `blindCast` so authors pick the right name at the call\n * site: a `castAs` is type-checked and benign; a `blindCast` is the unsafe escape\n * hatch. The split makes review faster — readers know which casts to scrutinize and\n * which are pure annotations.\n *\n * @example\n * ```typescript\n * interface FancyObject {\n *   key: string;\n *   keyTwo: {\n *     subKey: string;\n *     subKeyTwo: number;\n *   };\n * }\n *\n * const typedObject = castAs<FancyObject>({\n *   key: 'Chookede',\n *   keyTwo: {\n *     subKey: 'Choookeeeee',\n *     subKeyTwo: 2,\n *   },\n * });\n * ```\n *\n * @typeParam Type - The type to constrain and tag the value with. The value must be assignable to `Type`.\n */\nexport function castAs<Type>(value: Type): Type {\n  return value;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,UAA8C,OAA4B;CAGxF,OAAOA;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,OAAa,OAAmB;CAC9C,OAAO;AACT"}

package/dist/casts.d.mts

@@ -0,0 +1,77 @@
+//#region src/casts.d.ts
+/**
+ * **Last-resort escape hatch for unsafe type assertions. Not a sanctioned tool to reach for.**
+ *
+ * Before reaching for `blindCast`, **rewrite the surrounding code so the cast becomes
+ * unnecessary**: tighten an input type, add a runtime check that narrows via a type
+ * predicate, restructure a generic so the compiler can see the relationship you're
+ * asserting, or use {@link castAs} when the value already satisfies the target type.
+ * Only when no rewrite is feasible does `blindCast` become the right answer — and at
+ * that point, the `Reason` literal you supply must articulate the compromise in
+ * language a reviewer can evaluate.
+ *
+ * The reviewer **will** validate the `Reason`. If it doesn't hold up under scrutiny,
+ * that is not a signal to soften the reason; it is a signal to go back and solve the
+ * underlying type-system problem properly. An unconvincing justification is rework,
+ * not a free pass.
+ *
+ * `blindCast` is the auditable form of `as Foo` / `as unknown as Foo`: it bypasses
+ * the compiler's checks (the input type is `unknown`, the output type is whatever the
+ * caller asks for), but it forces the unsafety to be named at the call site instead of
+ * smuggled in via a bare `as`. The `Reason` type parameter exists only at compile
+ * time — it is not present in the emitted JavaScript — but it is grep-able and
+ * visible to future readers.
+ *
+ * @example
+ * ```typescript
+ * const stringValue = blindCast<
+ *   string,
+ *   "JSON.parse returns `unknown`; this field is documented to be a string in the API contract"
+ * >(parsed[key]);
+ * ```
+ *
+ * @typeParam TargetType - The type the caller is asserting the input has.
+ * @typeParam _Reason - A string literal describing why bypassing the type system is necessary here.
+ *                     Only meaningful at compile time. The reviewer evaluates whether it justifies the unsafety.
+ */
+declare function blindCast<TargetType, _Reason extends string>(input: unknown): TargetType;
+/**
+ * Type-checked, runtime pass-through alternative to a bare `as Type` cast.
+ *
+ * Use `castAs` when the value already satisfies the target type but you want to make
+ * the type assertion explicit at the call site — for example, when an inferred type is
+ * wider than the type you want to publish, or when a literal object should be tagged
+ * with its nominal interface. Unlike {@link blindCast}, the compiler still checks that
+ * the value is assignable to the target type, so this helper cannot smuggle in an
+ * unsafe assertion.
+ *
+ * `castAs` exists alongside `blindCast` so authors pick the right name at the call
+ * site: a `castAs` is type-checked and benign; a `blindCast` is the unsafe escape
+ * hatch. The split makes review faster — readers know which casts to scrutinize and
+ * which are pure annotations.
+ *
+ * @example
+ * ```typescript
+ * interface FancyObject {
+ *   key: string;
+ *   keyTwo: {
+ *     subKey: string;
+ *     subKeyTwo: number;
+ *   };
+ * }
+ *
+ * const typedObject = castAs<FancyObject>({
+ *   key: 'Chookede',
+ *   keyTwo: {
+ *     subKey: 'Choookeeeee',
+ *     subKeyTwo: 2,
+ *   },
+ * });
+ * ```
+ *
+ * @typeParam Type - The type to constrain and tag the value with. The value must be assignable to `Type`.
+ */
+declare function castAs<Type>(value: Type): Type;
+//#endregion
+export { blindCast, castAs };
+//# sourceMappingURL=casts.d.mts.map

package/dist/casts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"casts.d.mts","names":[],"sources":["../src/casts.ts"],"mappings":";;AAmCA;;;;;;;;;AAAyF;AA0CzF;;;;;;;;;AAA+C;;;;;;;;;;;;;;;iBA1C/B,SAAA,oCAAA,CAA8C,KAAA,YAAiB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0CzE,MAAA,MAAA,CAAa,KAAA,EAAO,IAAA,GAAO,IAAI"}

package/dist/casts.mjs

@@ -0,0 +1,2 @@
+import { n as castAs, t as blindCast } from "./casts-D2-X_DNw.mjs";
+export { blindCast, castAs };

package/dist/{defined-BYcWqtXq.mjs → defined-BnXRnErx.mjs}

@@ -27,4 +27,4 @@ function ifDefined(key, value) {
 //#endregion
 export { ifDefined as t };
 
-//# sourceMappingURL=defined-BYcWqtXq.mjs.map
+//# sourceMappingURL=defined-BnXRnErx.mjs.map

package/dist/{defined-BYcWqtXq.mjs.map → defined-BnXRnErx.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"defined-BYcWqtXq.mjs","names":[],"sources":["../src/defined.ts"],"sourcesContent":["/**\n * Returns an object with the key/value if value is defined, otherwise an empty object.\n *\n * Use with spread to conditionally include optional properties while satisfying\n * exactOptionalPropertyTypes. This is explicit about which properties are optional\n * and won't inadvertently strip other undefined values.\n *\n * @example\n * ```typescript\n * // Instead of:\n * const obj = {\n *   required: 'value',\n *   ...(optional ? { optional } : {}),\n * };\n *\n * // Use:\n * const obj = {\n *   required: 'value',\n *   ...ifDefined('optional', optional),\n * };\n * ```\n */\nexport function ifDefined<K extends string, V>(\n  key: K,\n  value: V | undefined,\n): Record<never, never> | { [P in K]: V } {\n  return value !== undefined ? ({ [key]: value } as { [P in K]: V }) : {};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,UACd,KACA,OACwC;CACxC,OAAO,UAAU,KAAA,IAAa,GAAG,MAAM,MAAM,IAAwB,CAAC;AACxE"}
+{"version":3,"file":"defined-BnXRnErx.mjs","names":[],"sources":["../src/defined.ts"],"sourcesContent":["/**\n * Returns an object with the key/value if value is defined, otherwise an empty object.\n *\n * Use with spread to conditionally include optional properties while satisfying\n * exactOptionalPropertyTypes. This is explicit about which properties are optional\n * and won't inadvertently strip other undefined values.\n *\n * @example\n * ```typescript\n * // Instead of:\n * const obj = {\n *   required: 'value',\n *   ...(optional ? { optional } : {}),\n * };\n *\n * // Use:\n * const obj = {\n *   required: 'value',\n *   ...ifDefined('optional', optional),\n * };\n * ```\n */\nexport function ifDefined<K extends string, V>(\n  key: K,\n  value: V | undefined,\n): Record<never, never> | { [P in K]: V } {\n  return value !== undefined ? ({ [key]: value } as { [P in K]: V }) : {};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,UACd,KACA,OACwC;CACxC,OAAO,UAAU,KAAA,IAAa,GAAG,MAAM,MAAM,IAAwB,CAAC;AACxE"}

package/dist/defined.mjs

@@ -1,2 +1,2 @@
-import { t as ifDefined } from "./defined-BYcWqtXq.mjs";
+import { t as ifDefined } from "./defined-BnXRnErx.mjs";
 export { ifDefined };

package/dist/redact-db-url.mjs

@@ -1,4 +1,4 @@
-import { t as ifDefined } from "./defined-BYcWqtXq.mjs";
+import { t as ifDefined } from "./defined-BnXRnErx.mjs";
 //#region src/redact-db-url.ts
 /**
 * Redacts a database connection URL to a minimal metadata object.

package/dist/result.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"result.d.mts","names":[],"sources":["../src/result.ts"],"mappings":";;AAeA;;;;;;;;;;;;AAIa;UAJI,EAAA;EAAA,SACN,EAAA;EAAA,SACA,KAAA,EAAO,CAAA;EAChB,QAAA,IAAY,CAAC;EACb,WAAA;AAAA;;;;UAMe,KAAA;EAAA,SACN,EAAA;EAAA,SACA,OAAA,EAAS,CAAA;EAClB,QAAA;EACA,WAAA,IAAe,CAAC;AAAA;;;;;;;KASN,MAAA,SAAe,EAAA,CAAG,CAAA,IAAK,KAAA,CAAM,CAAA;;;;iBAgFzB,EAAA,GAAA,CAAM,KAAA,EAAO,CAAA,GAAI,EAAA,CAAG,CAAA;;;;iBAOpB,KAAA,GAAA,CAAS,OAAA,EAAS,CAAA,GAAI,KAAA,CAAM,CAAA;AAP5C;;;;AAAA,iBAqBgB,MAAA,CAAA,GAAU,EAAE"}
+{"version":3,"file":"result.d.mts","names":[],"sources":["../src/result.ts"],"mappings":";;AAiBA;;;;;;;;;;;;AAIa;UAJI,EAAA;EAAA,SACN,EAAA;EAAA,SACA,KAAA,EAAO,CAAA;EAChB,QAAA,IAAY,CAAC;EACb,WAAA;AAAA;;;;UAMe,KAAA;EAAA,SACN,EAAA;EAAA,SACA,OAAA,EAAS,CAAA;EAClB,QAAA;EACA,WAAA,IAAe,CAAC;AAAA;;;;;;;KASN,MAAA,SAAe,EAAA,CAAG,CAAA,IAAK,KAAA,CAAM,CAAA;;;;iBAkFzB,EAAA,GAAA,CAAM,KAAA,EAAO,CAAA,GAAI,EAAA,CAAG,CAAA;;;;iBAOpB,KAAA,GAAA,CAAS,OAAA,EAAS,CAAA,GAAI,KAAA,CAAM,CAAA;AAP5C;;;;AAAA,iBAqBgB,MAAA,CAAA,GAAU,EAAE"}

package/dist/result.mjs

@@ -1,5 +1,17 @@
+import { t as blindCast } from "./casts-D2-X_DNw.mjs";
 //#region src/result.ts
 /**
+* Generic Result type for representing success or failure outcomes.
+*
+* This is the standard way to return "expected failures" as values rather than
+* throwing exceptions. See docs/Error Handling.md for the full taxonomy.
+*
+* Naming rationale:
+* - `Ok<T>` / `NotOk<F>` mirror the `ok: true/false` discriminator
+* - `NotOk` avoids collision with domain types like "Failure" or "Error"
+* - `failure` property distinguishes from JS Error semantics
+*/
+/**
 * Result class that implements both Ok and NotOk variants.
 */
 var ResultImpl = class ResultImpl {
@@ -24,13 +36,13 @@ var ResultImpl = class ResultImpl {
 	* Creates a successful result.
 	*/
 	static ok(value) {
-		return new ResultImpl(true, value);
+		return blindCast(new ResultImpl(true, value));
 	}
 	/**
 	* Creates an unsuccessful result.
 	*/
 	static notOk(failure) {
-		return new ResultImpl(false, failure);
+		return blindCast(new ResultImpl(false, failure));
 	}
 	/**
 	* Asserts that this result is Ok and returns the value.

package/dist/result.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"result.mjs","names":[],"sources":["../src/result.ts"],"sourcesContent":["/**\n * Generic Result type for representing success or failure outcomes.\n *\n * This is the standard way to return \"expected failures\" as values rather than\n * throwing exceptions. See docs/Error Handling.md for the full taxonomy.\n *\n * Naming rationale:\n * - `Ok<T>` / `NotOk<F>` mirror the `ok: true/false` discriminator\n * - `NotOk` avoids collision with domain types like \"Failure\" or \"Error\"\n * - `failure` property distinguishes from JS Error semantics\n */\n\n/**\n * Represents a successful result containing a value.\n */\nexport interface Ok<T> {\n  readonly ok: true;\n  readonly value: T;\n  assertOk(): T;\n  assertNotOk(): never;\n}\n\n/**\n * Represents an unsuccessful result containing failure details.\n */\nexport interface NotOk<F> {\n  readonly ok: false;\n  readonly failure: F;\n  assertOk(): never;\n  assertNotOk(): F;\n}\n\n/**\n * A discriminated union representing either success (Ok) or failure (NotOk).\n *\n * @typeParam T - The success value type\n * @typeParam F - The failure details type\n */\nexport type Result<T, F> = Ok<T> | NotOk<F>;\n\n/**\n * Result class that implements both Ok and NotOk variants.\n */\nclass ResultImpl<T, F> {\n  readonly ok: boolean;\n  private readonly _value?: T;\n  private readonly _failure?: F;\n\n  private constructor(ok: boolean, valueOrFailure: T | F) {\n    this.ok = ok;\n    if (ok) {\n      this._value = valueOrFailure as T;\n    } else {\n      this._failure = valueOrFailure as F;\n    }\n    Object.freeze(this);\n  }\n\n  get value(): T {\n    if (!this.ok) {\n      throw new Error('Cannot access value on NotOk result');\n    }\n    // biome-ignore lint/style/noNonNullAssertion: must be present if ok is true\n    return this._value!;\n  }\n\n  get failure(): F {\n    if (this.ok) {\n      throw new Error('Cannot access failure on Ok result');\n    }\n    // biome-ignore lint/style/noNonNullAssertion: must be present if ok is false\n    return this._failure!;\n  }\n\n  /**\n   * Creates a successful result.\n   */\n  static ok<T, F = never>(value: T): Ok<T> {\n    // TypeScript cannot express discriminated return types for a single implementation.\n    // Cast is safe: ok=true guarantees this is an Ok<T> at runtime.\n    return new ResultImpl<T, F>(true, value) as unknown as Ok<T>;\n  }\n\n  /**\n   * Creates an unsuccessful result.\n   */\n  static notOk<T = never, F = unknown>(failure: F): NotOk<F> {\n    // TypeScript cannot express discriminated return types for a single implementation.\n    // Cast is safe: ok=false guarantees this is a NotOk<F> at runtime.\n    return new ResultImpl<T, F>(false, failure) as unknown as NotOk<F>;\n  }\n\n  /**\n   * Asserts that this result is Ok and returns the value.\n   * Throws if the result is NotOk.\n   */\n  assertOk(this: Result<T, F>): T {\n    if (!this.ok) {\n      throw new Error('Expected Ok result but got NotOk');\n    }\n    return this.value;\n  }\n\n  /**\n   * Asserts that this result is NotOk and returns the failure.\n   * Throws if the result is Ok.\n   */\n  assertNotOk(this: Result<T, F>): F {\n    if (this.ok) {\n      throw new Error('Expected NotOk result but got Ok');\n    }\n    return this.failure;\n  }\n}\n\n/**\n * Creates a successful result.\n */\nexport function ok<T>(value: T): Ok<T> {\n  return ResultImpl.ok(value);\n}\n\n/**\n * Creates an unsuccessful result.\n */\nexport function notOk<F>(failure: F): NotOk<F> {\n  return ResultImpl.notOk(failure);\n}\n\n/**\n * Singleton for void success results.\n * Use this for validation checks that don't produce a value.\n */\nconst OK_VOID: Ok<void> = ResultImpl.ok<void>(undefined);\n\n/**\n * Returns a successful void result.\n * Use this for validation checks that don't produce a value.\n */\nexport function okVoid(): Ok<void> {\n  return OK_VOID;\n}\n"],"mappings":";;;;AA2CA,IAAM,aAAN,MAAM,WAAiB;CACrB;CACA;CACA;CAEA,YAAoB,IAAa,gBAAuB;EACtD,KAAK,KAAK;EACV,IAAI,IACF,KAAK,SAAS;OAEd,KAAK,WAAW;EAElB,OAAO,OAAO,IAAI;CACpB;CAEA,IAAI,QAAW;EACb,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,MAAM,qCAAqC;EAGvD,OAAO,KAAK;CACd;CAEA,IAAI,UAAa;EACf,IAAI,KAAK,IACP,MAAM,IAAI,MAAM,oCAAoC;EAGtD,OAAO,KAAK;CACd;;;;CAKA,OAAO,GAAiB,OAAiB;EAGvC,OAAO,IAAI,WAAiB,MAAM,KAAK;CACzC;;;;CAKA,OAAO,MAA8B,SAAsB;EAGzD,OAAO,IAAI,WAAiB,OAAO,OAAO;CAC5C;;;;;CAMA,WAAgC;EAC9B,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,MAAM,kCAAkC;EAEpD,OAAO,KAAK;CACd;;;;;CAMA,cAAmC;EACjC,IAAI,KAAK,IACP,MAAM,IAAI,MAAM,kCAAkC;EAEpD,OAAO,KAAK;CACd;AACF;;;;AAKA,SAAgB,GAAM,OAAiB;CACrC,OAAO,WAAW,GAAG,KAAK;AAC5B;;;;AAKA,SAAgB,MAAS,SAAsB;CAC7C,OAAO,WAAW,MAAM,OAAO;AACjC;;;;;AAMA,MAAM,UAAoB,WAAW,GAAS,KAAA,CAAS;;;;;AAMvD,SAAgB,SAAmB;CACjC,OAAO;AACT"}
+{"version":3,"file":"result.mjs","names":[],"sources":["../src/result.ts"],"sourcesContent":["/**\n * Generic Result type for representing success or failure outcomes.\n *\n * This is the standard way to return \"expected failures\" as values rather than\n * throwing exceptions. See docs/Error Handling.md for the full taxonomy.\n *\n * Naming rationale:\n * - `Ok<T>` / `NotOk<F>` mirror the `ok: true/false` discriminator\n * - `NotOk` avoids collision with domain types like \"Failure\" or \"Error\"\n * - `failure` property distinguishes from JS Error semantics\n */\n\nimport { blindCast } from './casts';\n\n/**\n * Represents a successful result containing a value.\n */\nexport interface Ok<T> {\n  readonly ok: true;\n  readonly value: T;\n  assertOk(): T;\n  assertNotOk(): never;\n}\n\n/**\n * Represents an unsuccessful result containing failure details.\n */\nexport interface NotOk<F> {\n  readonly ok: false;\n  readonly failure: F;\n  assertOk(): never;\n  assertNotOk(): F;\n}\n\n/**\n * A discriminated union representing either success (Ok) or failure (NotOk).\n *\n * @typeParam T - The success value type\n * @typeParam F - The failure details type\n */\nexport type Result<T, F> = Ok<T> | NotOk<F>;\n\n/**\n * Result class that implements both Ok and NotOk variants.\n */\nclass ResultImpl<T, F> {\n  readonly ok: boolean;\n  private readonly _value?: T;\n  private readonly _failure?: F;\n\n  private constructor(ok: boolean, valueOrFailure: T | F) {\n    this.ok = ok;\n    if (ok) {\n      this._value = valueOrFailure as T;\n    } else {\n      this._failure = valueOrFailure as F;\n    }\n    Object.freeze(this);\n  }\n\n  get value(): T {\n    if (!this.ok) {\n      throw new Error('Cannot access value on NotOk result');\n    }\n    // biome-ignore lint/style/noNonNullAssertion: must be present if ok is true\n    return this._value!;\n  }\n\n  get failure(): F {\n    if (this.ok) {\n      throw new Error('Cannot access failure on Ok result');\n    }\n    // biome-ignore lint/style/noNonNullAssertion: must be present if ok is false\n    return this._failure!;\n  }\n\n  /**\n   * Creates a successful result.\n   */\n  static ok<T, F = never>(value: T): Ok<T> {\n    return blindCast<\n      Ok<T>,\n      'ResultImpl is the single implementation of the Result discriminated union; TypeScript cannot express discriminated return types for a single class. ok=true guarantees this is an Ok<T> at runtime.'\n    >(new ResultImpl<T, F>(true, value));\n  }\n\n  /**\n   * Creates an unsuccessful result.\n   */\n  static notOk<T = never, F = unknown>(failure: F): NotOk<F> {\n    return blindCast<\n      NotOk<F>,\n      'ResultImpl is the single implementation of the Result discriminated union; TypeScript cannot express discriminated return types for a single class. ok=false guarantees this is a NotOk<F> at runtime.'\n    >(new ResultImpl<T, F>(false, failure));\n  }\n\n  /**\n   * Asserts that this result is Ok and returns the value.\n   * Throws if the result is NotOk.\n   */\n  assertOk(this: Result<T, F>): T {\n    if (!this.ok) {\n      throw new Error('Expected Ok result but got NotOk');\n    }\n    return this.value;\n  }\n\n  /**\n   * Asserts that this result is NotOk and returns the failure.\n   * Throws if the result is Ok.\n   */\n  assertNotOk(this: Result<T, F>): F {\n    if (this.ok) {\n      throw new Error('Expected NotOk result but got Ok');\n    }\n    return this.failure;\n  }\n}\n\n/**\n * Creates a successful result.\n */\nexport function ok<T>(value: T): Ok<T> {\n  return ResultImpl.ok(value);\n}\n\n/**\n * Creates an unsuccessful result.\n */\nexport function notOk<F>(failure: F): NotOk<F> {\n  return ResultImpl.notOk(failure);\n}\n\n/**\n * Singleton for void success results.\n * Use this for validation checks that don't produce a value.\n */\nconst OK_VOID: Ok<void> = ResultImpl.ok<void>(undefined);\n\n/**\n * Returns a successful void result.\n * Use this for validation checks that don't produce a value.\n */\nexport function okVoid(): Ok<void> {\n  return OK_VOID;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA6CA,IAAM,aAAN,MAAM,WAAiB;CACrB;CACA;CACA;CAEA,YAAoB,IAAa,gBAAuB;EACtD,KAAK,KAAK;EACV,IAAI,IACF,KAAK,SAAS;OAEd,KAAK,WAAW;EAElB,OAAO,OAAO,IAAI;CACpB;CAEA,IAAI,QAAW;EACb,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,MAAM,qCAAqC;EAGvD,OAAO,KAAK;CACd;CAEA,IAAI,UAAa;EACf,IAAI,KAAK,IACP,MAAM,IAAI,MAAM,oCAAoC;EAGtD,OAAO,KAAK;CACd;;;;CAKA,OAAO,GAAiB,OAAiB;EACvC,OAAO,UAGL,IAAI,WAAiB,MAAM,KAAK,CAAC;CACrC;;;;CAKA,OAAO,MAA8B,SAAsB;EACzD,OAAO,UAGL,IAAI,WAAiB,OAAO,OAAO,CAAC;CACxC;;;;;CAMA,WAAgC;EAC9B,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,MAAM,kCAAkC;EAEpD,OAAO,KAAK;CACd;;;;;CAMA,cAAmC;EACjC,IAAI,KAAK,IACP,MAAM,IAAI,MAAM,kCAAkC;EAEpD,OAAO,KAAK;CACd;AACF;;;;AAKA,SAAgB,GAAM,OAAiB;CACrC,OAAO,WAAW,GAAG,KAAK;AAC5B;;;;AAKA,SAAgB,MAAS,SAAsB;CAC7C,OAAO,WAAW,MAAM,OAAO;AACjC;;;;;AAMA,MAAM,UAAoB,WAAW,GAAS,KAAA,CAAS;;;;;AAMvD,SAAgB,SAAmB;CACjC,OAAO;AACT"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@prisma-next/utils",
-  "version": "0.11.0-dev.14",
+  "version": "0.11.0-dev.15",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Shared utility functions for Prisma Next",
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.11.0-dev.14",
-    "@prisma-next/tsdown": "0.11.0-dev.14",
+    "@prisma-next/tsconfig": "0.11.0-dev.15",
+    "@prisma-next/tsdown": "0.11.0-dev.15",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
@@ -24,6 +24,7 @@
     "./array-equal": "./dist/array-equal.mjs",
     "./assertions": "./dist/assertions.mjs",
     "./canonical-stringify": "./dist/canonical-stringify.mjs",
+    "./casts": "./dist/casts.mjs",
     "./defined": "./dist/defined.mjs",
     "./hash-content": "./dist/hash-content.mjs",
     "./json": "./dist/json.mjs",

package/src/casts.ts

@@ -0,0 +1,80 @@
+/**
+ * **Last-resort escape hatch for unsafe type assertions. Not a sanctioned tool to reach for.**
+ *
+ * Before reaching for `blindCast`, **rewrite the surrounding code so the cast becomes
+ * unnecessary**: tighten an input type, add a runtime check that narrows via a type
+ * predicate, restructure a generic so the compiler can see the relationship you're
+ * asserting, or use {@link castAs} when the value already satisfies the target type.
+ * Only when no rewrite is feasible does `blindCast` become the right answer — and at
+ * that point, the `Reason` literal you supply must articulate the compromise in
+ * language a reviewer can evaluate.
+ *
+ * The reviewer **will** validate the `Reason`. If it doesn't hold up under scrutiny,
+ * that is not a signal to soften the reason; it is a signal to go back and solve the
+ * underlying type-system problem properly. An unconvincing justification is rework,
+ * not a free pass.
+ *
+ * `blindCast` is the auditable form of `as Foo` / `as unknown as Foo`: it bypasses
+ * the compiler's checks (the input type is `unknown`, the output type is whatever the
+ * caller asks for), but it forces the unsafety to be named at the call site instead of
+ * smuggled in via a bare `as`. The `Reason` type parameter exists only at compile
+ * time — it is not present in the emitted JavaScript — but it is grep-able and
+ * visible to future readers.
+ *
+ * @example
+ * ```typescript
+ * const stringValue = blindCast<
+ *   string,
+ *   "JSON.parse returns `unknown`; this field is documented to be a string in the API contract"
+ * >(parsed[key]);
+ * ```
+ *
+ * @typeParam TargetType - The type the caller is asserting the input has.
+ * @typeParam _Reason - A string literal describing why bypassing the type system is necessary here.
+ *                     Only meaningful at compile time. The reviewer evaluates whether it justifies the unsafety.
+ */
+export function blindCast<TargetType, _Reason extends string>(input: unknown): TargetType {
+  // biome-ignore lint/suspicious/noExplicitAny: this helper is the single canonical escape hatch for type-unsafe casts in the codebase; the `any` is hyper-local, the unsafety is made explicit at every call site via the call's own `Reason` literal, and the reviewer evaluates whether that justification holds
+  const x: any = input;
+  return x;
+}
+
+/**
+ * Type-checked, runtime pass-through alternative to a bare `as Type` cast.
+ *
+ * Use `castAs` when the value already satisfies the target type but you want to make
+ * the type assertion explicit at the call site — for example, when an inferred type is
+ * wider than the type you want to publish, or when a literal object should be tagged
+ * with its nominal interface. Unlike {@link blindCast}, the compiler still checks that
+ * the value is assignable to the target type, so this helper cannot smuggle in an
+ * unsafe assertion.
+ *
+ * `castAs` exists alongside `blindCast` so authors pick the right name at the call
+ * site: a `castAs` is type-checked and benign; a `blindCast` is the unsafe escape
+ * hatch. The split makes review faster — readers know which casts to scrutinize and
+ * which are pure annotations.
+ *
+ * @example
+ * ```typescript
+ * interface FancyObject {
+ *   key: string;
+ *   keyTwo: {
+ *     subKey: string;
+ *     subKeyTwo: number;
+ *   };
+ * }
+ *
+ * const typedObject = castAs<FancyObject>({
+ *   key: 'Chookede',
+ *   keyTwo: {
+ *     subKey: 'Choookeeeee',
+ *     subKeyTwo: 2,
+ *   },
+ * });
+ * ```
+ *
+ * @typeParam Type - The type to constrain and tag the value with. The value must be assignable to `Type`.
+ */
+export function castAs<Type>(value: Type): Type {
+  return value;
+}

package/src/exports/casts.ts

@@ -0,0 +1 @@
+export { blindCast, castAs } from '../casts';

package/src/result.ts

@@ -10,6 +10,8 @@
  * - `failure` property distinguishes from JS Error semantics
  */
 
+import { blindCast } from './casts';
+
 /**
  * Represents a successful result containing a value.
  */
@@ -76,18 +78,20 @@ class ResultImpl<T, F> {
    * Creates a successful result.
    */
   static ok<T, F = never>(value: T): Ok<T> {
-    // TypeScript cannot express discriminated return types for a single implementation.
-    // Cast is safe: ok=true guarantees this is an Ok<T> at runtime.
-    return new ResultImpl<T, F>(true, value) as unknown as Ok<T>;
+    return blindCast<
+      Ok<T>,
+      'ResultImpl is the single implementation of the Result discriminated union; TypeScript cannot express discriminated return types for a single class. ok=true guarantees this is an Ok<T> at runtime.'
+    >(new ResultImpl<T, F>(true, value));
   }
 
   /**
    * Creates an unsuccessful result.
    */
   static notOk<T = never, F = unknown>(failure: F): NotOk<F> {
-    // TypeScript cannot express discriminated return types for a single implementation.
-    // Cast is safe: ok=false guarantees this is a NotOk<F> at runtime.
-    return new ResultImpl<T, F>(false, failure) as unknown as NotOk<F>;
+    return blindCast<
+      NotOk<F>,
+      'ResultImpl is the single implementation of the Result discriminated union; TypeScript cannot express discriminated return types for a single class. ok=false guarantees this is a NotOk<F> at runtime.'
+    >(new ResultImpl<T, F>(false, failure));
   }
 
   /**