@clipboard-health/contract-core 2.2.42 → 2.3.0

package/README.md

@@ -19,6 +19,10 @@ npm install @clipboard-health/contract-core
 
 ### Zod schemas
 
+#### DateTime schema
+
+`dateTimeSchema()` validates strict ISO-8601 datetime strings and transforms them to `Date` objects. Unlike `z.coerce.date()`, it rejects loose inputs like epoch numbers and date-only strings. Composable with `.optional()`, `.nullable()`, etc. at the call site.
+
 #### Enum validation helpers
 
 This package provides four enum validation helpers to cover different use cases:
@@ -39,6 +43,7 @@ This package provides four enum validation helpers to cover different use cases:
 import {
   apiErrors,
   booleanString,
+  dateTimeSchema,
   nonEmptyString,
   optionalEnum,
   optionalEnumWithFallback,
@@ -90,6 +95,39 @@ try {
   // => Invalid UUID format
 }
 
+// DateTime schema examples
+// Validates strict ISO-8601 datetime strings and transforms to Date objects.
+// Composable with .optional(), .nullable(), etc.
+const createdAt = dateTimeSchema().parse("2026-03-15T10:30:00.000Z");
+// => Date object
+console.log(createdAt instanceof Date); // true
+console.log(createdAt.toISOString()); // "2026-03-15T10:30:00.000Z"
+
+try {
+  dateTimeSchema().parse("2026-03-15"); // date-only string
+} catch (error) {
+  logError(error);
+  // => Invalid datetime
+}
+
+try {
+  dateTimeSchema().parse(1_773_340_050_000); // epoch number
+} catch (error) {
+  logError(error);
+  // => Expected string, received number
+}
+
+// Optional usage — compose at the call site
+const schema = dateTimeSchema().optional();
+// eslint-disable-next-line unicorn/no-useless-undefined
+const noDate = schema.parse(undefined);
+// => undefined
+console.log(noDate);
+
+const someDate = schema.parse("2026-03-15T10:30:00.000Z");
+// => Date object
+console.log(someDate);
+
 // Enum with fallback examples
 /* -- required -- */
 const requiredStatusEnumSchema = requiredEnumWithFallback(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/contract-core",
   "description": "Shared Zod schemas for Clipboard's contracts.",
-  "version": "2.2.42",
+  "version": "2.3.0",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
     "tslib": "2.8.1"

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

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Validates that the input is a strict ISO-8601 datetime string,
+ * then transforms it into a Date object.
+ *
+ * Composable with `.optional()`, `.nullable()`, etc. at the call site:
+ * ```ts
+ * z.object({
+ *   start: dateTimeSchema(),
+ *   clockIn: dateTimeSchema().optional(),
+ * });
+ * ```
+ *
+ * z.input  → string (what callers send over the wire)
+ * z.output → Date   (what callers receive after parsing)
+ *
+ * Requires `parsedApi.ts` so that schemas are parsed at runtime.
+ */
+export declare function dateTimeSchema(): z.ZodEffects<z.ZodString, Date, string>;

package/src/lib/schemas/dateTime.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dateTimeSchema = dateTimeSchema;
+const zod_1 = require("zod");
+/**
+ * Validates that the input is a strict ISO-8601 datetime string,
+ * then transforms it into a Date object.
+ *
+ * Composable with `.optional()`, `.nullable()`, etc. at the call site:
+ * ```ts
+ * z.object({
+ *   start: dateTimeSchema(),
+ *   clockIn: dateTimeSchema().optional(),
+ * });
+ * ```
+ *
+ * z.input  → string (what callers send over the wire)
+ * z.output → Date   (what callers receive after parsing)
+ *
+ * Requires `parsedApi.ts` so that schemas are parsed at runtime.
+ */
+function dateTimeSchema() {
+    return zod_1.z
+        .string()
+        .datetime()
+        .transform((value) => new Date(value));
+}
+//# sourceMappingURL=dateTime.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dateTime.js","sourceRoot":"","sources":["../../../../../../packages/contract-core/src/lib/schemas/dateTime.ts"],"names":[],"mappings":";;AAmBA,wCAKC;AAxBD,6BAAwB;AAExB;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc;IAC5B,OAAO,OAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3C,CAAC"}

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

@@ -1,5 +1,6 @@
 export * from "./apiError";
 export * from "./booleanString";
+export * from "./dateTime";
 export * from "./enum";
 export * from "./money";
 export * from "./nonEmptyString";

package/src/lib/schemas/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./apiError"), exports);
 tslib_1.__exportStar(require("./booleanString"), exports);
+tslib_1.__exportStar(require("./dateTime"), exports);
 tslib_1.__exportStar(require("./enum"), exports);
 tslib_1.__exportStar(require("./money"), exports);
 tslib_1.__exportStar(require("./nonEmptyString"), exports);

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/contract-core/src/lib/schemas/index.ts"],"names":[],"mappings":";;;AAAA,qDAA2B;AAC3B,0DAAgC;AAChC,iDAAuB;AACvB,kDAAwB;AACxB,2DAAiC;AACjC,qDAA2B;AAC3B,iDAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/contract-core/src/lib/schemas/index.ts"],"names":[],"mappings":";;;AAAA,qDAA2B;AAC3B,0DAAgC;AAChC,qDAA2B;AAC3B,iDAAuB;AACvB,kDAAwB;AACxB,2DAAiC;AACjC,qDAA2B;AAC3B,iDAAuB"}