@clipboard-health/contract-core 1.6.10 → 1.6.11

package/README.md

@@ -19,6 +19,20 @@ npm install @clipboard-health/contract-core
 
 ### Zod schemas
 
+#### Enum validation helpers
+
+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`.
+
+**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.
+
 <embedex source="packages/contract-core/examples/schemas.ts">
 
 ```ts
@@ -26,7 +40,9 @@ import {
   apiErrors,
   booleanString,
   nonEmptyString,
+  optionalEnum,
   optionalEnumWithFallback,
+  requiredEnum,
   requiredEnumWithFallback,
   uuid,
 } from "@clipboard-health/contract-core";
@@ -119,6 +135,55 @@ console.log(extraStatus);
 const undefinedStatus = optionalStatusEnumSchema.parse(undefined);
 // => undefined
 console.log(undefinedStatus);
+
+// Strict enum examples (no fallback behavior)
+// Use these when invalid values should fail validation rather than being coerced.
+// Ideal for user types, authentication, and critical business logic.
+
+/* -- required strict -- */
+const requiredUserTypeSchema = requiredEnum(["admin", "worker", "facility"]);
+// type RequiredUserType = "admin" | "worker" | "facility"
+type RequiredUserType = z.infer<typeof requiredUserTypeSchema>;
+
+const adminUser: RequiredUserType = requiredUserTypeSchema.parse("admin");
+// => "admin"
+console.log(adminUser);
+
+try {
+  requiredUserTypeSchema.parse("invalid");
+} catch (error) {
+  logError(error);
+  // => Invalid enum value. Expected 'admin' | 'worker' | 'facility', received 'invalid'
+}
+
+try {
+  // eslint-disable-next-line unicorn/no-useless-undefined
+  requiredUserTypeSchema.parse(undefined);
+} catch (error) {
+  logError(error);
+  // => Required
+}
+
+/* -- optional strict -- */
+const optionalUserTypeSchema = optionalEnum(["admin", "worker", "facility"]);
+// type OptionalUserType = "admin" | "worker" | "facility" | undefined
+type OptionalUserType = z.infer<typeof optionalUserTypeSchema>;
+
+const workerUser: OptionalUserType = optionalUserTypeSchema.parse("worker");
+// => "worker"
+console.log(workerUser);
+
+// eslint-disable-next-line unicorn/no-useless-undefined
+const noUserType = optionalUserTypeSchema.parse(undefined);
+// => undefined
+console.log(noUserType);
+
+try {
+  optionalUserTypeSchema.parse("invalid");
+} catch (error) {
+  logError(error);
+  // => Invalid enum value. Expected 'admin' | 'worker' | 'facility', received 'invalid'
+}
 ```
 
 </embedex>

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@clipboard-health/contract-core",
   "description": "Shared Zod schemas for Clipboard's contracts.",
-  "version": "1.6.10",
+  "version": "1.6.11",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@clipboard-health/testing-core": "1.6.10",
+    "@clipboard-health/testing-core": "1.6.11",
     "zod": "3.25.76"
   },
   "keywords": [

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

@@ -5,4 +5,6 @@ export declare function enumWithFallback<const V extends EnumValues, const F ext
 }): 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>>;
 export {};

package/src/lib/schemas/enum.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requiredEnumWithFallback = exports.optionalEnumWithFallback = void 0;
 exports.enumWithFallback = enumWithFallback;
+exports.requiredEnum = requiredEnum;
+exports.optionalEnum = optionalEnum;
 const zod_1 = require("zod");
 function enumWithFallback(values, fallback, options = {}) {
     const Enum = zod_1.z.enum(values);
@@ -18,4 +20,10 @@ const optionalEnumWithFallback = (values, fallback) => enumWithFallback(values,
 exports.optionalEnumWithFallback = optionalEnumWithFallback;
 const requiredEnumWithFallback = (values, fallback) => enumWithFallback(values, fallback, { optional: false });
 exports.requiredEnumWithFallback = requiredEnumWithFallback;
+function requiredEnum(values) {
+    return zod_1.z.enum(values);
+}
+function optionalEnum(values) {
+    return zod_1.z.enum(values).optional();
+}
 //# sourceMappingURL=enum.js.map

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;AAvCD,6BAAwB;AAwBxB,SAAgB,gBAAgB,CAC9B,MAAS,EACT,QAAW,EACX,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,OAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,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"}
+{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../../../../../packages/contract-core/src/lib/schemas/enum.ts"],"names":[],"mappings":";;;AAwBA,4CAeC;AAYD,oCAEC;AAED,oCAEC;AAzDD,6BAAwB;AAwBxB,SAAgB,gBAAgB,CAC9B,MAAS,EACT,QAAW,EACX,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,OAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,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,MAAM,CAAC,CAAC;AACxB,CAAC;AAED,SAAgB,YAAY,CAA6B,MAAS;IAChE,OAAO,OAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;AACnC,CAAC"}