@pawells/typescript-common 2.1.5 → 2.1.6

package/dist/zod-util.d.ts

@@ -0,0 +1,145 @@
+import { SemVer } from 'semver';
+import { z } from 'zod/v4';
+/**
+ * Zod schema for MongoDB ObjectId validation.
+ *
+ * Validates 24-character hexadecimal strings that conform to MongoDB's ObjectId format.
+ *
+ * @returns {z.ZodType<string>} Zod schema that validates ObjectId format
+ *
+ * @example
+ * const id = OBJECT_ID_SCHEMA.parse('507f1f77bcf86cd799439011');
+ * // Type: string
+ *
+ * @example
+ * const result = OBJECT_ID_SCHEMA.safeParse('invalid');
+ * // { success: false, error: ZodError }
+ */
+export declare const OBJECT_ID_SCHEMA: z.ZodString;
+/**
+ * Type inferred from OBJECT_ID_SCHEMA.
+ *
+ * Represents a valid MongoDB ObjectId string (24 hex characters).
+ */
+export type TObjectId = z.infer<typeof OBJECT_ID_SCHEMA>;
+/**
+ * Zod schema for semantic version validation.
+ *
+ * Transforms valid semantic version strings into SemVer instances. Zod schemas validate
+ * and return results rather than throw errors. Use .parse() to throw on invalid input,
+ * or .safeParse() to return a Result object.
+ *
+ * @returns {z.ZodType<SemVer>} Zod schema that parses and transforms to SemVer instance
+ *
+ * @remarks
+ * Invalid inputs throw errors when using .parse(), but .safeParse() returns a failure Result
+ * without throwing. The transform produces a SemVer instance rather than a string.
+ *
+ * @example
+ * const version = SEMVER_SCHEMA.parse('1.2.3');
+ * console.log(version.major); // 1
+ *
+ * @example
+ * const result = SEMVER_SCHEMA.safeParse('invalid');
+ * if (!result.success) {
+ *   console.error('Invalid semver:', result.error);
+ * }
+ */
+export declare const SEMVER_SCHEMA: z.ZodPipe<z.ZodString, z.ZodTransform<SemVer, string>>;
+/**
+ * Zod validator for ZodObject schemas (z.object()).
+ *
+ * Uses instanceof check to validate that a value is a Zod object schema.
+ * Useful for runtime type guards when working with Zod schemas dynamically.
+ *
+ * @returns {z.ZodType<ZodObject<ZodRawShape>>} Zod schema that validates ZodObject instances
+ *
+ * @warning When using across module boundaries or in bundled environments,
+ * instanceof checks may fail due to multiple ZodObject constructor instances.
+ * If you encounter false negatives, consider using ZodObject method inspection
+ * as an alternative validation strategy.
+ *
+ * @example
+ * const schema = z.object({ name: z.string() });
+ * ZOD_OBJECT_SCHEMA.parse(schema); // OK
+ * ZOD_OBJECT_SCHEMA.parse("not a schema"); // throws ZodError
+ */
+export declare const ZOD_OBJECT_SCHEMA: z.ZodCustom<z.ZodObject<Readonly<{
+    [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}>, z.core.$strip>, z.ZodObject<Readonly<{
+    [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}>, z.core.$strip>>;
+/**
+ * Type inferred from ZOD_OBJECT_SCHEMA.
+ *
+ * Represents a Zod object schema with arbitrary shape.
+ */
+export type TZodObjectSchema = z.infer<typeof ZOD_OBJECT_SCHEMA>;
+/**
+ * Recursive type for JSON-serializable values.
+ *
+ * Represents any value that can be safely serialized to JSON: primitives, arrays, or objects
+ * with string keys and JSON-serializable values. Null is included but undefined is not.
+ */
+export type TJSONSerializable = string | number | boolean | null | TJSONSerializable[] | {
+    [key: string]: TJSONSerializable;
+};
+/**
+ * Zod schema for generic JSON-serializable values.
+ *
+ * Validates that input conforms to the JSON-serializable type: strings, numbers, booleans,
+ * null, arrays, and objects with string keys. Uses lazy evaluation to support recursive
+ * structures without infinite type expansion.
+ *
+ * @returns {z.ZodType<TJSONSerializable>} Zod schema that validates JSON-serializable values
+ *
+ * @remarks
+ * This schema uses z.lazy() to enable recursive validation of nested structures.
+ * Undefined values and functions are rejected; only JSON-safe primitives and containers are allowed.
+ *
+ * @example
+ * JSON_SERIALIZABLE_SCHEMA.parse({ name: 'Alice', age: 30, tags: ['a', 'b'] }); // OK
+ *
+ * @example
+ * JSON_SERIALIZABLE_SCHEMA.parse({ fn: () => {} }); // throws ZodError (function not allowed)
+ */
+export declare const JSON_SERIALIZABLE_SCHEMA: z.ZodType<TJSONSerializable>;
+/**
+ * Zod schema for generic JSON objects.
+ *
+ * Validates that input is an object with string keys and JSON-serializable values.
+ * More restrictive than JSON_SERIALIZABLE_SCHEMA because it disallows arrays and primitives
+ * at the root level.
+ *
+ * @returns {z.ZodType} Zod schema that validates JSON objects with string keys
+ *
+ * @example
+ * JSON_OBJECT_SCHEMA.parse({ a: 1, b: 'hello', c: null }); // OK
+ *
+ * @example
+ * JSON_OBJECT_SCHEMA.parse([1, 2, 3]); // throws ZodError (array not allowed at root)
+ */
+export declare const JSON_OBJECT_SCHEMA: z.ZodRecord<z.ZodString, z.ZodType<TJSONSerializable, unknown, z.core.$ZodTypeInternals<TJSONSerializable, unknown>>>;
+/**
+ * Zod schema for JSON date string validation.
+ *
+ * Transforms date strings into Date instances. Accepts any string format recognized by the Date constructor
+ * (ISO 8601, timestamp, etc.). Note that invalid date strings produce Invalid Date objects (NaN value)
+ * rather than throwing errors.
+ *
+ * @returns {z.ZodType<Date>} Zod schema that parses and transforms strings to Date instances
+ *
+ * @remarks
+ * Invalid date strings produce Invalid Date objects (NaN value), not errors. Use `.refine(d => !isNaN(d.getTime()))`
+ * if you need to reject invalid dates and only accept valid date strings.
+ *
+ * @example
+ * const date = JSON_DATE_SCHEMA.parse('2024-01-15T10:30:00Z');
+ * console.log(date.getFullYear()); // 2024
+ *
+ * @example
+ * const invalidDate = JSON_DATE_SCHEMA.parse('not-a-date');
+ * console.log(invalidDate.getTime()); // NaN
+ */
+export declare const JSON_DATE_SCHEMA: z.ZodPipe<z.ZodString, z.ZodTransform<Date, string>>;
+//# sourceMappingURL=zod-util.d.ts.map

package/dist/zod-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-util.d.ts","sourceRoot":"","sources":["../src/zod-util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,CAAC,EAAoC,MAAM,QAAQ,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,aAAyD,CAAC;AAEvF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,aAAa,wDAAiD,CAAC;AAE5E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB;;;;mBAG7B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,iBAAiB,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAE9H;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CASjE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,uHAAiD,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,sDAA+C,CAAC"}

package/dist/zod-util.js

@@ -0,0 +1,126 @@
+import { SemVer } from 'semver';
+import { z } from 'zod/v4';
+/**
+ * Zod schema for MongoDB ObjectId validation.
+ *
+ * Validates 24-character hexadecimal strings that conform to MongoDB's ObjectId format.
+ *
+ * @returns {z.ZodType<string>} Zod schema that validates ObjectId format
+ *
+ * @example
+ * const id = OBJECT_ID_SCHEMA.parse('507f1f77bcf86cd799439011');
+ * // Type: string
+ *
+ * @example
+ * const result = OBJECT_ID_SCHEMA.safeParse('invalid');
+ * // { success: false, error: ZodError }
+ */
+export const OBJECT_ID_SCHEMA = z.string().regex(/^[a-f\d]{24}$/i, 'Invalid ObjectId');
+/**
+ * Zod schema for semantic version validation.
+ *
+ * Transforms valid semantic version strings into SemVer instances. Zod schemas validate
+ * and return results rather than throw errors. Use .parse() to throw on invalid input,
+ * or .safeParse() to return a Result object.
+ *
+ * @returns {z.ZodType<SemVer>} Zod schema that parses and transforms to SemVer instance
+ *
+ * @remarks
+ * Invalid inputs throw errors when using .parse(), but .safeParse() returns a failure Result
+ * without throwing. The transform produces a SemVer instance rather than a string.
+ *
+ * @example
+ * const version = SEMVER_SCHEMA.parse('1.2.3');
+ * console.log(version.major); // 1
+ *
+ * @example
+ * const result = SEMVER_SCHEMA.safeParse('invalid');
+ * if (!result.success) {
+ *   console.error('Invalid semver:', result.error);
+ * }
+ */
+export const SEMVER_SCHEMA = z.string().transform((val) => new SemVer(val));
+/**
+ * Zod validator for ZodObject schemas (z.object()).
+ *
+ * Uses instanceof check to validate that a value is a Zod object schema.
+ * Useful for runtime type guards when working with Zod schemas dynamically.
+ *
+ * @returns {z.ZodType<ZodObject<ZodRawShape>>} Zod schema that validates ZodObject instances
+ *
+ * @warning When using across module boundaries or in bundled environments,
+ * instanceof checks may fail due to multiple ZodObject constructor instances.
+ * If you encounter false negatives, consider using ZodObject method inspection
+ * as an alternative validation strategy.
+ *
+ * @example
+ * const schema = z.object({ name: z.string() });
+ * ZOD_OBJECT_SCHEMA.parse(schema); // OK
+ * ZOD_OBJECT_SCHEMA.parse("not a schema"); // throws ZodError
+ */
+export const ZOD_OBJECT_SCHEMA = z.custom((val) => val instanceof z.ZodObject, { message: "Must be a Zod object schema" });
+/**
+ * Zod schema for generic JSON-serializable values.
+ *
+ * Validates that input conforms to the JSON-serializable type: strings, numbers, booleans,
+ * null, arrays, and objects with string keys. Uses lazy evaluation to support recursive
+ * structures without infinite type expansion.
+ *
+ * @returns {z.ZodType<TJSONSerializable>} Zod schema that validates JSON-serializable values
+ *
+ * @remarks
+ * This schema uses z.lazy() to enable recursive validation of nested structures.
+ * Undefined values and functions are rejected; only JSON-safe primitives and containers are allowed.
+ *
+ * @example
+ * JSON_SERIALIZABLE_SCHEMA.parse({ name: 'Alice', age: 30, tags: ['a', 'b'] }); // OK
+ *
+ * @example
+ * JSON_SERIALIZABLE_SCHEMA.parse({ fn: () => {} }); // throws ZodError (function not allowed)
+ */
+export const JSON_SERIALIZABLE_SCHEMA = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JSON_SERIALIZABLE_SCHEMA),
+    z.record(z.string(), JSON_SERIALIZABLE_SCHEMA),
+]));
+/**
+ * Zod schema for generic JSON objects.
+ *
+ * Validates that input is an object with string keys and JSON-serializable values.
+ * More restrictive than JSON_SERIALIZABLE_SCHEMA because it disallows arrays and primitives
+ * at the root level.
+ *
+ * @returns {z.ZodType} Zod schema that validates JSON objects with string keys
+ *
+ * @example
+ * JSON_OBJECT_SCHEMA.parse({ a: 1, b: 'hello', c: null }); // OK
+ *
+ * @example
+ * JSON_OBJECT_SCHEMA.parse([1, 2, 3]); // throws ZodError (array not allowed at root)
+ */
+export const JSON_OBJECT_SCHEMA = z.record(z.string(), JSON_SERIALIZABLE_SCHEMA);
+/**
+ * Zod schema for JSON date string validation.
+ *
+ * Transforms date strings into Date instances. Accepts any string format recognized by the Date constructor
+ * (ISO 8601, timestamp, etc.). Note that invalid date strings produce Invalid Date objects (NaN value)
+ * rather than throwing errors.
+ *
+ * @returns {z.ZodType<Date>} Zod schema that parses and transforms strings to Date instances
+ *
+ * @remarks
+ * Invalid date strings produce Invalid Date objects (NaN value), not errors. Use `.refine(d => !isNaN(d.getTime()))`
+ * if you need to reject invalid dates and only accept valid date strings.
+ *
+ * @example
+ * const date = JSON_DATE_SCHEMA.parse('2024-01-15T10:30:00Z');
+ * console.log(date.getFullYear()); // 2024
+ *
+ * @example
+ * const invalidDate = JSON_DATE_SCHEMA.parse('not-a-date');
+ * console.log(invalidDate.getTime()); // NaN
+ */
+export const JSON_DATE_SCHEMA = z.string().transform((val) => new Date(val));

package/package.json

@@ -1,60 +1,67 @@
 {
-  "name": "@pawells/typescript-common",
-  "displayName": "TypeScript Common Library",
-  "description": "Shared TypeScript utility library",
-  "version": "2.1.5",
-  "license": "MIT",
-  "author": {
-    "name": "Phillip Aaron Wells",
-    "email": "phillip.aaron.wells@gmail.com"
-  },
-  "homepage": "https://github.com/PhillipAWells/typescript-common",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/PhillipAWells/typescript-common.git"
-  },
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/PhillipAWells"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "@pawells/typescript-common-workspace": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "!**/*.tsbuildinfo"
-  ],
-  "keywords": [
-    "typescript",
-    "utilities",
-    "common",
-    "library"
-  ],
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "nx": {
-    "name": "@pawells/typescript-common",
-    "tags": [
-      "npm:public"
-    ],
-    "targets": {
-      "clean": {
-        "executor": "nx:run-commands",
-        "options": {
-          "command": "rm -rf dist tsconfig.*.tsbuildinfo",
-          "cwd": "packages/typescript-common"
-        }
-      }
-    }
-  }
+	"name": "@pawells/typescript-common",
+	"displayName": "TypeScript Common Library",
+	"description": "Shared TypeScript utility library",
+	"version": "2.1.6",
+	"license": "MIT",
+	"author": {
+		"name": "Phillip Aaron Wells",
+		"email": "phillip.aaron.wells@gmail.com"
+	},
+	"homepage": "https://github.com/PhillipAWells/common",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/PhillipAWells/common.git"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/PhillipAWells"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"@pawells/typescript-common-workspace": "./src/index.ts",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!**/*.tsbuildinfo"
+	],
+	"keywords": [
+		"typescript",
+		"utilities",
+		"common",
+		"library"
+	],
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"nx": {
+		"name": "@pawells/typescript-common",
+		"tags": [
+			"npm:public"
+		],
+		"targets": {
+			"clean": {
+				"executor": "nx:run-commands",
+				"options": {
+					"command": "rm -rf dist tsconfig.*.tsbuildinfo",
+					"cwd": "packages/typescript-common"
+				}
+			}
+		}
+	},
+	"dependencies": {
+		"semver": "7.8.0",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@types/semver": "^7.7.1"
+	}
 }