@fuzdev/fuz_util 0.53.1 → 0.53.3

package/dist/bytes.d.ts

@@ -11,4 +11,11 @@
  * @returns `Uint8Array` view of the data.
  */
 export declare const to_bytes: (data: BufferSource | string) => Uint8Array;
+/**
+ * Formats a byte count as a human-readable string.
+ *
+ * @param n - byte count.
+ * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`.
+ */
+export declare const format_bytes: (n: number) => string;
 //# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bytes.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/bytes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,YAAY,GAAG,MAAM,KAAG,UAKtD,CAAC"}
+{"version":3,"file":"bytes.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/bytes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,YAAY,GAAG,MAAM,KAAG,UAKtD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,MAKxC,CAAC"}

package/dist/bytes.js

@@ -20,3 +20,18 @@ export const to_bytes = (data) => {
         return new Uint8Array(data);
     return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 };
+/**
+ * Formats a byte count as a human-readable string.
+ *
+ * @param n - byte count.
+ * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`.
+ */
+export const format_bytes = (n) => {
+    if (n < 1024)
+        return n + ' B';
+    if (n < 1024 * 1024)
+        return (n / 1024).toFixed(1) + ' KB';
+    if (n < 1024 * 1024 * 1024)
+        return (n / (1024 * 1024)).toFixed(1) + ' MB';
+    return (n / (1024 * 1024 * 1024)).toFixed(1) + ' GB';
+};

package/dist/hash_blake3.d.ts

@@ -2,9 +2,17 @@
  * BLAKE3 cryptographic hashing via `@fuzdev/blake3_wasm`.
  *
  * Synchronous and fast. Returns hex-encoded 256-bit (32-byte) digests.
+ * WASM initialization starts eagerly on import. Await `blake3_ready` before first use
+ * in browser contexts where the WASM must be fetched asynchronously.
  *
  * @module
  */
+/**
+ * Resolves when the BLAKE3 WASM module is initialized and ready.
+ * Initialization starts eagerly on import. Idempotent — safe to await multiple times.
+ * In Node.js/Deno (sync init), this resolves immediately.
+ */
+export declare const blake3_ready: Promise<void>;
 /**
  * Computes a BLAKE3 hash synchronously.
  *

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;;;;;;GAMG;AAOH;;;;;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;AAOH;;;;GAIG;AACH,eAAO,MAAM,YAAY,eAAS,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,YAAY,GAAG,MAAM,KAAG,MAAsC,CAAC"}

package/dist/hash_blake3.js

@@ -2,12 +2,20 @@
  * BLAKE3 cryptographic hashing via `@fuzdev/blake3_wasm`.
  *
  * Synchronous and fast. Returns hex-encoded 256-bit (32-byte) digests.
+ * WASM initialization starts eagerly on import. Await `blake3_ready` before first use
+ * in browser contexts where the WASM must be fetched asynchronously.
  *
  * @module
  */
-import { hash } from '@fuzdev/blake3_wasm';
+import { hash, init } from '@fuzdev/blake3_wasm';
 import { to_hex } from './hex.js';
 import { to_bytes } from './bytes.js';
+/**
+ * Resolves when the BLAKE3 WASM module is initialized and ready.
+ * Initialization starts eagerly on import. Idempotent — safe to await multiple times.
+ * In Node.js/Deno (sync init), this resolves immediately.
+ */
+export const blake3_ready = init();
 /**
  * Computes a BLAKE3 hash synchronously.
  *

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.1",
+  "version": "0.53.3",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",

package/src/lib/bytes.ts

@@ -19,3 +19,16 @@ export const to_bytes = (data: BufferSource | string): Uint8Array => {
 	if (data instanceof ArrayBuffer) return new Uint8Array(data);
 	return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 };
+
+/**
+ * Formats a byte count as a human-readable string.
+ *
+ * @param n - byte count.
+ * @returns formatted string like `'1.2 KB'` or `'3.4 MB'`.
+ */
+export const format_bytes = (n: number): string => {
+	if (n < 1024) return n + ' B';
+	if (n < 1024 * 1024) return (n / 1024).toFixed(1) + ' KB';
+	if (n < 1024 * 1024 * 1024) return (n / (1024 * 1024)).toFixed(1) + ' MB';
+	return (n / (1024 * 1024 * 1024)).toFixed(1) + ' GB';
+};

package/src/lib/hash_blake3.ts

@@ -2,15 +2,24 @@
  * BLAKE3 cryptographic hashing via `@fuzdev/blake3_wasm`.
  *
  * Synchronous and fast. Returns hex-encoded 256-bit (32-byte) digests.
+ * WASM initialization starts eagerly on import. Await `blake3_ready` before first use
+ * in browser contexts where the WASM must be fetched asynchronously.
  *
  * @module
  */
 
-import {hash} from '@fuzdev/blake3_wasm';
+import {hash, init} from '@fuzdev/blake3_wasm';
 
 import {to_hex} from './hex.js';
 import {to_bytes} from './bytes.js';
 
+/**
+ * Resolves when the BLAKE3 WASM module is initialized and ready.
+ * Initialization starts eagerly on import. Idempotent — safe to await multiple times.
+ * In Node.js/Deno (sync init), this resolves immediately.
+ */
+export const blake3_ready = init();
+
 /**
  * Computes a BLAKE3 hash synchronously.
  *

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.
  *