@fuzdev/fuz_util 0.53.2 → 0.53.4

package/dist/hash_blake3.d.ts

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { z } from 'zod';
 /**
  * Resolves when the BLAKE3 WASM module is initialized and ready.
  * Initialization starts eagerly on import. Idempotent — safe to await multiple times.
@@ -20,4 +21,7 @@ export declare const blake3_ready: Promise<void>;
  * @returns 64-character hexadecimal hash string (32 bytes).
  */
 export declare const hash_blake3: (data: BufferSource | string) => string;
+/** Zod schema for a BLAKE3 hex hash — 64 lowercase hex characters (256-bit output). */
+export declare const Blake3Hash: z.ZodString;
+export type Blake3Hash = z.infer<typeof Blake3Hash>;
 //# sourceMappingURL=hash_blake3.d.ts.map

package/dist/hash_blake3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash_blake3.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hash_blake3.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAS,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,YAAY,GAAG,MAAM,KAAG,MAAsC,CAAC"}
+{"version":3,"file":"hash_blake3.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hash_blake3.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAS,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,YAAY,GAAG,MAAM,KAAG,MAAsC,CAAC;AAEjG,uFAAuF;AACvF,eAAO,MAAM,UAAU,aAEuD,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/hash_blake3.js

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { z } from 'zod';
 import { hash, init } from '@fuzdev/blake3_wasm';
 import { to_hex } from './hex.js';
 import { to_bytes } from './bytes.js';
@@ -23,3 +24,7 @@ export const blake3_ready = init();
  * @returns 64-character hexadecimal hash string (32 bytes).
  */
 export const hash_blake3 = (data) => to_hex(hash(to_bytes(data)));
+/** Zod schema for a BLAKE3 hex hash — 64 lowercase hex characters (256-bit output). */
+export const Blake3Hash = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/, 'Expected a 64-character lowercase hex blake3 hash');

package/dist/zod.d.ts

@@ -1,8 +1,8 @@
 /**
  * Zod schema introspection utilities.
  *
- * Generic helpers for extracting metadata from Zod schemas.
- * Designed for CLI argument parsing but applicable elsewhere.
+ * Generic helpers for walking, unwrapping, and extracting metadata from Zod schemas.
+ * Used by CLI argument parsing, adversarial input testing, and surface generation.
  *
  * @module
  */
@@ -14,6 +14,67 @@ import type { z } from 'zod';
  * @returns Inner schema if wrapped, undefined otherwise.
  */
 export declare const zod_to_subschema: (def: z.core.$ZodTypeDef) => z.ZodType | undefined;
+/** Zod wrapper type names that `zod_unwrap_def` traverses through. */
+export declare const ZOD_WRAPPER_TYPES: Set<string>;
+/**
+ * Unwrap Zod wrappers (optional, default, nullable, pipe, transform)
+ * to get the base type definition.
+ *
+ * @param schema - Zod schema to unwrap
+ * @returns the innermost non-wrapper type definition
+ */
+export declare const zod_unwrap_def: (schema: z.ZodType) => z.core.$ZodTypeDef;
+/**
+ * Get the base type name for a Zod schema, unwrapping all wrappers.
+ *
+ * @param schema - Zod schema to inspect
+ * @returns base type name (e.g. `'string'`, `'object'`, `'uuid'`)
+ */
+export declare const zod_get_base_type: (schema: z.ZodType) => string;
+/**
+ * Check if a schema is optional at the outermost level.
+ *
+ * @param schema - Zod schema to check
+ */
+export declare const zod_is_optional: (schema: z.ZodType) => boolean;
+/**
+ * Check if a schema accepts null at any wrapping level.
+ *
+ * @param schema - Zod schema to check
+ */
+export declare const zod_is_nullable: (schema: z.ZodType) => boolean;
+/**
+ * Check if a schema has a default value at any wrapping level.
+ *
+ * Unlike `zod_to_schema_default` (which returns the value), this returns a boolean.
+ * Distinguishes "no default" from "default is undefined".
+ *
+ * @param schema - Zod schema to check
+ */
+export declare const zod_has_default: (schema: z.ZodType) => boolean;
+/**
+ * Unwrap a schema to find the inner `ZodObject`, or `null` if not an object schema.
+ * Handles wrappers like `z.strictObject({...}).default({...})`.
+ *
+ * @param schema - Zod schema to unwrap
+ * @returns the inner ZodObject or null
+ */
+export declare const zod_unwrap_to_object: (schema: z.ZodType) => z.ZodObject | null;
+/** Metadata extracted from a single field of a Zod object schema. */
+export interface ZodFieldInfo {
+    name: string;
+    base_type: string;
+    required: boolean;
+    has_default: boolean;
+    nullable: boolean;
+}
+/**
+ * Extract field metadata from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from
+ * @returns array of field info for each property
+ */
+export declare const zod_extract_fields: (schema: z.ZodObject) => Array<ZodFieldInfo>;
 /**
  * Get the description from a schema's metadata, unwrapping if needed.
  *

package/dist/zod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAM3B;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,KAAG,CAAC,CAAC,OAAO,GAAG,SAStE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAAM,GAAG,IAUtE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAUzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,MAAM,CAUrE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MA4C7D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,MAQjD,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,iBAAiB,CAuBnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,GAAG,CAAC,MAAM,CAW9E,CAAC"}
+{"version":3,"file":"zod.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAM3B;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,KAAG,CAAC,CAAC,OAAO,GAAG,SAStE,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,aAO5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,CAAC,CAAC,IAAI,CAAC,WAOzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAAqC,CAAC;AAE5F;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAA8C,CAAC;AAEnG;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAQnD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAMnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,CAAC,CAAC,SAAS,GAAG,IAUtE,CAAC;AAIF,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,YAAY,CAa1E,CAAC;AAIF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MAAM,GAAG,IAUtE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAUzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,MAAM,CAUrE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,MA4C7D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,MAQjD,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,iBAAiB,CAuBnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,GAAG,CAAC,MAAM,CAW9E,CAAC"}

package/dist/zod.js

@@ -1,8 +1,8 @@
 /**
  * Zod schema introspection utilities.
  *
- * Generic helpers for extracting metadata from Zod schemas.
- * Designed for CLI argument parsing but applicable elsewhere.
+ * Generic helpers for walking, unwrapping, and extracting metadata from Zod schemas.
+ * Used by CLI argument parsing, adversarial input testing, and surface generation.
  *
  * @module
  */
@@ -27,6 +27,118 @@ export const zod_to_subschema = (def) => {
     }
     return undefined;
 };
+/** Zod wrapper type names that `zod_unwrap_def` traverses through. */
+export const ZOD_WRAPPER_TYPES = new Set([
+    'optional',
+    'nullable',
+    'default',
+    'transform',
+    'pipe',
+    'prefault',
+]);
+/**
+ * Unwrap Zod wrappers (optional, default, nullable, pipe, transform)
+ * to get the base type definition.
+ *
+ * @param schema - Zod schema to unwrap
+ * @returns the innermost non-wrapper type definition
+ */
+export const zod_unwrap_def = (schema) => {
+    const def = schema._zod.def;
+    if (ZOD_WRAPPER_TYPES.has(def.type)) {
+        const sub = zod_to_subschema(def);
+        if (sub)
+            return zod_unwrap_def(sub);
+    }
+    return def;
+};
+/**
+ * Get the base type name for a Zod schema, unwrapping all wrappers.
+ *
+ * @param schema - Zod schema to inspect
+ * @returns base type name (e.g. `'string'`, `'object'`, `'uuid'`)
+ */
+export const zod_get_base_type = (schema) => zod_unwrap_def(schema).type;
+/**
+ * Check if a schema is optional at the outermost level.
+ *
+ * @param schema - Zod schema to check
+ */
+export const zod_is_optional = (schema) => schema._zod.def.type === 'optional';
+/**
+ * Check if a schema accepts null at any wrapping level.
+ *
+ * @param schema - Zod schema to check
+ */
+export const zod_is_nullable = (schema) => {
+    const def = schema._zod.def;
+    if (def.type === 'nullable')
+        return true;
+    if (ZOD_WRAPPER_TYPES.has(def.type)) {
+        const sub = zod_to_subschema(def);
+        if (sub)
+            return zod_is_nullable(sub);
+    }
+    return false;
+};
+/**
+ * Check if a schema has a default value at any wrapping level.
+ *
+ * Unlike `zod_to_schema_default` (which returns the value), this returns a boolean.
+ * Distinguishes "no default" from "default is undefined".
+ *
+ * @param schema - Zod schema to check
+ */
+export const zod_has_default = (schema) => {
+    const def = schema._zod.def;
+    if ('defaultValue' in def)
+        return true;
+    const sub = zod_to_subschema(def);
+    if (sub)
+        return zod_has_default(sub);
+    return false;
+};
+/**
+ * Unwrap a schema to find the inner `ZodObject`, or `null` if not an object schema.
+ * Handles wrappers like `z.strictObject({...}).default({...})`.
+ *
+ * @param schema - Zod schema to unwrap
+ * @returns the inner ZodObject or null
+ */
+export const zod_unwrap_to_object = (schema) => {
+    const def = zod_unwrap_def(schema);
+    if (def.type !== 'object')
+        return null;
+    let s = schema;
+    while (s._zod.def.type !== 'object') {
+        const sub = zod_to_subschema(s._zod.def);
+        if (!sub)
+            return null;
+        s = sub;
+    }
+    return s;
+};
+/**
+ * Extract field metadata from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from
+ * @returns array of field info for each property
+ */
+export const zod_extract_fields = (schema) => {
+    const fields = [];
+    for (const [name, field_schema] of Object.entries(schema.shape)) {
+        const field = field_schema;
+        fields.push({
+            name,
+            base_type: zod_get_base_type(field),
+            required: !zod_is_optional(field),
+            has_default: zod_has_default(field),
+            nullable: zod_is_nullable(field),
+        });
+    }
+    return fields;
+};
+// --- Metadata extraction ---
 /**
  * Get the description from a schema's metadata, unwrapping if needed.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.53.2",
+  "version": "0.53.4",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -81,7 +81,7 @@
     "@fuzdev/fuz_ui": "^0.185.2",
     "@fuzdev/gro": "^0.197.0",
     "@jridgewell/trace-mapping": "^0.3.31",
-    "@ryanatkn/eslint-config": "^0.10.0",
+    "@ryanatkn/eslint-config": "^0.10.1",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",

package/src/lib/hash_blake3.ts

@@ -8,6 +8,7 @@
  * @module
  */
 
+import {z} from 'zod';
 import {hash, init} from '@fuzdev/blake3_wasm';
 
 import {to_hex} from './hex.js';
@@ -27,3 +28,9 @@ export const blake3_ready = init();
  * @returns 64-character hexadecimal hash string (32 bytes).
  */
 export const hash_blake3 = (data: BufferSource | string): string => to_hex(hash(to_bytes(data)));
+
+/** Zod schema for a BLAKE3 hex hash — 64 lowercase hex characters (256-bit output). */
+export const Blake3Hash = z
+	.string()
+	.regex(/^[0-9a-f]{64}$/, 'Expected a 64-character lowercase hex blake3 hash');
+export type Blake3Hash = z.infer<typeof Blake3Hash>;

package/src/lib/zod.ts

@@ -1,8 +1,8 @@
 /**
  * Zod schema introspection utilities.
  *
- * Generic helpers for extracting metadata from Zod schemas.
- * Designed for CLI argument parsing but applicable elsewhere.
+ * Generic helpers for walking, unwrapping, and extracting metadata from Zod schemas.
+ * Used by CLI argument parsing, adversarial input testing, and surface generation.
  *
  * @module
  */
@@ -30,6 +30,131 @@ export const zod_to_subschema = (def: z.core.$ZodTypeDef): z.ZodType | undefined
 	return undefined;
 };
 
+/** Zod wrapper type names that `zod_unwrap_def` traverses through. */
+export const ZOD_WRAPPER_TYPES = new Set([
+	'optional',
+	'nullable',
+	'default',
+	'transform',
+	'pipe',
+	'prefault',
+]);
+
+/**
+ * Unwrap Zod wrappers (optional, default, nullable, pipe, transform)
+ * to get the base type definition.
+ *
+ * @param schema - Zod schema to unwrap
+ * @returns the innermost non-wrapper type definition
+ */
+export const zod_unwrap_def = (schema: z.ZodType): z.core.$ZodTypeDef => {
+	const def = schema._zod.def;
+	if (ZOD_WRAPPER_TYPES.has(def.type)) {
+		const sub = zod_to_subschema(def);
+		if (sub) return zod_unwrap_def(sub);
+	}
+	return def;
+};
+
+/**
+ * Get the base type name for a Zod schema, unwrapping all wrappers.
+ *
+ * @param schema - Zod schema to inspect
+ * @returns base type name (e.g. `'string'`, `'object'`, `'uuid'`)
+ */
+export const zod_get_base_type = (schema: z.ZodType): string => zod_unwrap_def(schema).type;
+
+/**
+ * Check if a schema is optional at the outermost level.
+ *
+ * @param schema - Zod schema to check
+ */
+export const zod_is_optional = (schema: z.ZodType): boolean => schema._zod.def.type === 'optional';
+
+/**
+ * Check if a schema accepts null at any wrapping level.
+ *
+ * @param schema - Zod schema to check
+ */
+export const zod_is_nullable = (schema: z.ZodType): boolean => {
+	const def = schema._zod.def;
+	if (def.type === 'nullable') return true;
+	if (ZOD_WRAPPER_TYPES.has(def.type)) {
+		const sub = zod_to_subschema(def);
+		if (sub) return zod_is_nullable(sub);
+	}
+	return false;
+};
+
+/**
+ * Check if a schema has a default value at any wrapping level.
+ *
+ * Unlike `zod_to_schema_default` (which returns the value), this returns a boolean.
+ * Distinguishes "no default" from "default is undefined".
+ *
+ * @param schema - Zod schema to check
+ */
+export const zod_has_default = (schema: z.ZodType): boolean => {
+	const def = schema._zod.def;
+	if ('defaultValue' in def) return true;
+	const sub = zod_to_subschema(def);
+	if (sub) return zod_has_default(sub);
+	return false;
+};
+
+/**
+ * Unwrap a schema to find the inner `ZodObject`, or `null` if not an object schema.
+ * Handles wrappers like `z.strictObject({...}).default({...})`.
+ *
+ * @param schema - Zod schema to unwrap
+ * @returns the inner ZodObject or null
+ */
+export const zod_unwrap_to_object = (schema: z.ZodType): z.ZodObject | null => {
+	const def = zod_unwrap_def(schema);
+	if (def.type !== 'object') return null;
+	let s: z.ZodType = schema;
+	while (s._zod.def.type !== 'object') {
+		const sub = zod_to_subschema(s._zod.def);
+		if (!sub) return null;
+		s = sub;
+	}
+	return s as z.ZodObject;
+};
+
+// --- Field extraction ---
+
+/** Metadata extracted from a single field of a Zod object schema. */
+export interface ZodFieldInfo {
+	name: string;
+	base_type: string;
+	required: boolean;
+	has_default: boolean;
+	nullable: boolean;
+}
+
+/**
+ * Extract field metadata from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from
+ * @returns array of field info for each property
+ */
+export const zod_extract_fields = (schema: z.ZodObject): Array<ZodFieldInfo> => {
+	const fields: Array<ZodFieldInfo> = [];
+	for (const [name, field_schema] of Object.entries(schema.shape)) {
+		const field = field_schema as z.ZodType;
+		fields.push({
+			name,
+			base_type: zod_get_base_type(field),
+			required: !zod_is_optional(field),
+			has_default: zod_has_default(field),
+			nullable: zod_is_nullable(field),
+		});
+	}
+	return fields;
+};
+
+// --- Metadata extraction ---
+
 /**
  * Get the description from a schema's metadata, unwrapping if needed.
  *