@clipboard-health/contract-core 2.3.47 → 3.1.0

package/README.md

@@ -29,14 +29,29 @@ This package provides four enum validation helpers to cover different use cases:
 
 **Fallback validation (with coalescing):**
 
-- `requiredEnumWithFallback(values, fallback)` - Invalid values are coerced to the fallback value. `undefined` fails validation.
-- `optionalEnumWithFallback(values, fallback)` - Invalid values are coerced to the fallback value. `undefined` passes through as `undefined`.
+- `requiredEnumWithFallback(values)` - Invalid values are coerced to `ENUM_FALLBACK` (`"UNRECOGNIZED_"`), a business-context-neutral sentinel automatically appended to the enum type. `undefined` fails validation.
+- `optionalEnumWithFallback(values)` - Invalid values are coerced to `ENUM_FALLBACK` (`"UNRECOGNIZED_"`). `undefined` passes through as `undefined`.
 
 **Strict validation (no fallback):**
 
 - `requiredEnum(values)` - Wraps `z.enum()` for required strict validation. Invalid values fail validation.
 - `optionalEnum(values)` - Wraps `z.enum()` for optional strict validation. Invalid values fail validation, but `undefined` is allowed.
 
+**Type narrowing:** All helpers reject widened `string[]` arrays at compile time. When passing a pre-declared variable, use `as const` to preserve literal types:
+
+```ts
+// Inline arrays work as-is
+requiredEnum(["a", "b"]);
+
+// Pre-declared variables require `as const`
+const VALUES = ["a", "b"] as const;
+requiredEnum(VALUES);
+
+// Without `as const`, the type widens to string[] and is rejected
+const widened = ["a", "b"];
+requiredEnum(widened); // TS error
+```
+
 <embedex source="packages/contract-core/examples/schemas.ts">
 
 ```ts
@@ -44,6 +59,7 @@ import {
   apiErrors,
   booleanString,
   dateTimeSchema,
+  ENUM_FALLBACK,
   nonEmptyString,
   optionalEnum,
   optionalEnumWithFallback,
@@ -134,12 +150,13 @@ const someDate = schema.parse("2026-03-15T10:30:00.000Z");
 console.log(someDate);
 
 // Enum with fallback examples
+// ENUM_FALLBACK is a neutral sentinel ("UNRECOGNIZED_") automatically appended
+// to the enum type. Consumers cannot choose their own fallback value, preventing
+// misuse where a business-meaningful value is treated as a default.
+
 /* -- required -- */
-const requiredStatusEnumSchema = requiredEnumWithFallback(
-  ["unspecified", "pending", "completed", "failed"],
-  "unspecified",
-);
-// type RequiredStatusEnum = "unspecified" | "pending" | "completed" | "failed"
+const requiredStatusEnumSchema = requiredEnumWithFallback(["pending", "completed", "failed"]);
+// type RequiredStatusEnum = "pending" | "completed" | "failed" | "UNRECOGNIZED_"
 type RequiredStatusEnum = z.infer<typeof requiredStatusEnumSchema>;
 
 const completedStatus: RequiredStatusEnum = requiredStatusEnumSchema.parse("completed");
@@ -147,8 +164,9 @@ const completedStatus: RequiredStatusEnum = requiredStatusEnumSchema.parse("comp
 console.log(completedStatus);
 
 const additionalStatus = requiredStatusEnumSchema.parse("additional");
-// => "unspecified"
+// => "UNRECOGNIZED_" (ENUM_FALLBACK)
 console.log(additionalStatus);
+console.log(additionalStatus === ENUM_FALLBACK); // true
 
 try {
   // eslint-disable-next-line unicorn/no-useless-undefined
@@ -159,11 +177,8 @@ try {
 }
 
 /* -- optional -- */
-const optionalStatusEnumSchema = optionalEnumWithFallback(
-  ["unspecified", "pending", "completed", "failed"],
-  "unspecified",
-);
-// type OptionalStatusEnum = "unspecified" | "pending" | "completed" | "failed" | undefined
+const optionalStatusEnumSchema = optionalEnumWithFallback(["pending", "completed", "failed"]);
+// type OptionalStatusEnum = "pending" | "completed" | "failed" | "UNRECOGNIZED_" | undefined
 type OptionalStatusEnum = z.infer<typeof optionalStatusEnumSchema>;
 
 const failedStatus: OptionalStatusEnum = optionalStatusEnumSchema.parse("failed");
@@ -171,7 +186,7 @@ const failedStatus: OptionalStatusEnum = optionalStatusEnumSchema.parse("failed"
 console.log(failedStatus);
 
 const extraStatus = optionalStatusEnumSchema.parse("extra");
-// => "unspecified"
+// => "UNRECOGNIZED_" (ENUM_FALLBACK)
 console.log(extraStatus);
 
 // eslint-disable-next-line unicorn/no-useless-undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/contract-core",
-  "version": "2.3.47",
+  "version": "3.1.0",
   "description": "Shared Zod schemas for Clipboard's contracts.",
   "keywords": [
     "contract",

package/src/lib/schemas/enum.d.ts

@@ -1,10 +1,17 @@
 import { z } from "zod";
 type EnumValues = readonly [string, ...string[]];
-export declare function enumWithFallback<const V extends EnumValues, const F extends V[number]>(values: V, fallback: F, options: {
+type NarrowEnum<V extends EnumValues> = string extends V[number] ? never : V;
+/**
+ * A business-context-neutral sentinel returned when an enum field
+ * receives a value the consumer does not recognize.
+ */
+export declare const ENUM_FALLBACK: "UNRECOGNIZED_";
+type EnumFallback = typeof ENUM_FALLBACK;
+export declare function enumWithFallback<const V extends EnumValues>(values: NarrowEnum<V>, options: {
     optional: true;
-}): z.ZodEffects<z.ZodOptional<z.ZodEnum<[...V]>>, V[number] | undefined, unknown>;
-export declare const optionalEnumWithFallback: <const V extends EnumValues, const F extends V[number]>(values: V, fallback: F) => z.ZodEffects<z.ZodOptional<z.ZodEnum<[...V]>>, V[number] | undefined, unknown>;
-export declare const requiredEnumWithFallback: <const V extends EnumValues, const F extends V[number]>(values: V, fallback: F) => z.ZodEffects<z.ZodEnum<[...V]>, V[number], unknown>;
-export declare function requiredEnum<const V extends EnumValues>(values: V): z.ZodEnum<[...V]>;
-export declare function optionalEnum<const V extends EnumValues>(values: V): z.ZodOptional<z.ZodEnum<[...V]>>;
+}): z.ZodEffects<z.ZodOptional<z.ZodEnum<[...V, EnumFallback]>>, V[number] | EnumFallback | undefined, unknown>;
+export declare function requiredEnumWithFallback<const V extends EnumValues>(values: NarrowEnum<V>): z.ZodEffects<z.ZodEnum<[...V, "UNRECOGNIZED_"]>, "UNRECOGNIZED_" | V[number], unknown>;
+export declare function optionalEnumWithFallback<const V extends EnumValues>(values: NarrowEnum<V>): z.ZodEffects<z.ZodOptional<z.ZodEnum<[...V, "UNRECOGNIZED_"]>>, "UNRECOGNIZED_" | V[number] | undefined, unknown>;
+export declare function requiredEnum<const V extends EnumValues>(values: NarrowEnum<V>): z.ZodEnum<[...V]>;
+export declare function optionalEnum<const V extends EnumValues>(values: NarrowEnum<V>): z.ZodOptional<z.ZodEnum<[...V]>>;
 export {};

package/src/lib/schemas/enum.js

@@ -1,25 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requiredEnumWithFallback = exports.optionalEnumWithFallback = void 0;
+exports.ENUM_FALLBACK = void 0;
 exports.enumWithFallback = enumWithFallback;
+exports.requiredEnumWithFallback = requiredEnumWithFallback;
+exports.optionalEnumWithFallback = optionalEnumWithFallback;
 exports.requiredEnum = requiredEnum;
 exports.optionalEnum = optionalEnum;
 const zod_1 = require("zod");
-function enumWithFallback(values, fallback, options = {}) {
-    const Enum = zod_1.z.enum([...values]);
+/**
+ * A business-context-neutral sentinel returned when an enum field
+ * receives a value the consumer does not recognize.
+ */
+exports.ENUM_FALLBACK = "UNRECOGNIZED_";
+function enumWithFallback(values, options = {}) {
+    if (values.includes(exports.ENUM_FALLBACK)) {
+        throw new Error(`Enum values must not include "${exports.ENUM_FALLBACK}". It is appended automatically.`);
+    }
+    const OriginalEnum = zod_1.z.enum([...values]);
+    const ExpandedEnum = zod_1.z.enum([...values, exports.ENUM_FALLBACK]);
     const optional = options.optional ?? false;
-    const schema = optional ? Enum.optional() : Enum;
+    const schema = optional ? ExpandedEnum.optional() : ExpandedEnum;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     return zod_1.z.preprocess((value) => {
         if (value === undefined) {
             return optional ? undefined : value;
         }
-        return Enum.safeParse(value).success ? value : fallback;
+        return OriginalEnum.safeParse(value).success ? value : exports.ENUM_FALLBACK;
     }, schema);
 }
-const optionalEnumWithFallback = (values, fallback) => enumWithFallback(values, fallback, { optional: true });
-exports.optionalEnumWithFallback = optionalEnumWithFallback;
-const requiredEnumWithFallback = (values, fallback) => enumWithFallback(values, fallback, { optional: false });
-exports.requiredEnumWithFallback = requiredEnumWithFallback;
+function requiredEnumWithFallback(values) {
+    return enumWithFallback(values, { optional: false });
+}
+function optionalEnumWithFallback(values) {
+    return enumWithFallback(values, { optional: true });
+}
 function requiredEnum(values) {
     return zod_1.z.enum([...values]);
 }

package/src/lib/schemas/enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../../../../../packages/contract-core/src/lib/schemas/enum.ts"],"names":[],"mappings":";;;AAwBA,4CAeC;AAYD,oCAEC;AAED,oCAIC;AA3DD,6BAAwB;AAwBxB,SAAgB,gBAAgB,CAC9B,MAAS,EACT,QAAW,EACX,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAEjD,OAAO,OAAC,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE;QAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1D,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC;AAEM,MAAM,wBAAwB,GAAG,CACtC,MAAS,EACT,QAAW,EACX,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAH/C,QAAA,wBAAwB,4BAGuB;AAErD,MAAM,wBAAwB,GAAG,CACtC,MAAS,EACT,QAAW,EACX,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AAHhD,QAAA,wBAAwB,4BAGwB;AAE7D,SAAgB,YAAY,CAA6B,MAAS;IAChE,OAAO,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,SAAgB,YAAY,CAC1B,MAAS;IAET,OAAO,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../../../../../packages/contract-core/src/lib/schemas/enum.ts"],"names":[],"mappings":";;;AAkCA,4CAuBC;AAED,4DAEC;AAED,4DAEC;AAED,oCAEC;AAED,oCAIC;AA3ED,6BAAwB;AAKxB;;;GAGG;AACU,QAAA,aAAa,GAAG,eAAwB,CAAC;AAyBtD,SAAgB,gBAAgB,CAC9B,MAAS,EACT,UAAkC,EAAE;IAEpC,IAAK,MAA4B,CAAC,QAAQ,CAAC,qBAAa,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,iCAAiC,qBAAa,kCAAkC,CACjF,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,EAAE,qBAAa,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;IAEjE,+DAA+D;IAC/D,OAAO,OAAC,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE;QAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;QACtC,CAAC;QAED,OAAO,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAa,CAAC;IACvE,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC;AAED,SAAgB,wBAAwB,CAA6B,MAAqB;IACxF,OAAO,gBAAgB,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,SAAgB,wBAAwB,CAA6B,MAAqB;IACxF,OAAO,gBAAgB,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,SAAgB,YAAY,CAA6B,MAAqB;IAC5E,OAAO,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,SAAgB,YAAY,CAC1B,MAAqB;IAErB,OAAO,OAAC,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACxC,CAAC"}