@fuzdev/fuz_util 0.51.0 → 0.52.1

package/dist/async.d.ts

@@ -8,7 +8,7 @@ export declare const wait: (duration?: number) => Promise<void>;
  */
 export declare const is_promise: (value: unknown) => value is Promise<unknown>;
 /**
- * Creates a deferred object with a promise and its resolve/reject handlers.
+ * A deferred object with a promise and its resolve/reject handlers.
  */
 export interface Deferred<T> {
     promise: Promise<T>;
@@ -16,57 +16,63 @@ export interface Deferred<T> {
     reject: (reason: any) => void;
 }
 /**
- * Creates a object with a `promise` and its `resolve`/`reject` handlers.
+ * Creates an object with a `promise` and its `resolve`/`reject` handlers.
  */
 export declare const create_deferred: <T>() => Deferred<T>;
 /**
- * Runs an async function on each item with controlled concurrency.
+ * Runs a function on each item with controlled concurrency.
  * Like `map_concurrent` but doesn't collect results (more efficient for side effects).
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  *
  * @example
  * ```ts
  * await each_concurrent(
  *   file_paths,
- *   async (path) => { await unlink(path); },
  *   5, // max 5 concurrent deletions
+ *   async (path) => { await unlink(path); },
  * );
  * ```
  */
-export declare const each_concurrent: <T>(items: Array<T>, fn: (item: T, index: number) => Promise<void>, concurrency: number) => Promise<void>;
+export declare const each_concurrent: <T>(items: Iterable<T>, concurrency: number, fn: (item: T, index: number) => Promise<void> | void, signal?: AbortSignal) => Promise<void>;
 /**
  * Maps over items with controlled concurrency, preserving input order.
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of results in same order as input
  *
  * @example
  * ```ts
  * const results = await map_concurrent(
  *   file_paths,
- *   async (path) => readFile(path, 'utf8'),
  *   5, // max 5 concurrent reads
+ *   async (path) => readFile(path, 'utf8'),
  * );
  * ```
  */
-export declare const map_concurrent: <T, R>(items: Array<T>, fn: (item: T, index: number) => Promise<R>, concurrency: number) => Promise<Array<R>>;
+export declare const map_concurrent: <T, R>(items: Iterable<T>, concurrency: number, fn: (item: T, index: number) => Promise<R> | R, signal?: AbortSignal) => Promise<Array<R>>;
 /**
  * Like `map_concurrent` but collects all results/errors instead of failing fast.
  * Returns an array of settlement objects matching the `Promise.allSettled` pattern.
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * On abort, resolves with partial results: completed items keep their real settlements,
+ * in-flight and un-started items are settled as rejected with the abort reason.
+ *
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of `PromiseSettledResult` objects in input order
  *
  * @example
  * ```ts
- * const results = await map_concurrent_settled(urls, fetch, 5);
+ * const results = await map_concurrent_settled(urls, 5, fetch);
  * for (const [i, result] of results.entries()) {
  *   if (result.status === 'fulfilled') {
  *     console.log(`${urls[i]}: ${result.value.status}`);
@@ -76,7 +82,7 @@ export declare const map_concurrent: <T, R>(items: Array<T>, fn: (item: T, index
  * }
  * ```
  */
-export declare const map_concurrent_settled: <T, R>(items: Array<T>, fn: (item: T, index: number) => Promise<R>, concurrency: number) => Promise<Array<PromiseSettledResult<R>>>;
+export declare const map_concurrent_settled: <T, R>(items: Iterable<T>, concurrency: number, fn: (item: T, index: number) => Promise<R> | R, signal?: AbortSignal) => Promise<Array<PromiseSettledResult<R>>>;
 /**
  * Async semaphore for concurrency limiting.
  *

package/dist/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EACtC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAC7C,aAAa,MAAM,KACjB,OAAO,CAAC,IAAI,CAgDd,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAkDlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6CxC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,cAAc;;gBAId,OAAO,EAAE,MAAM;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,OAAO,IAAI,IAAI;CAQf"}
+{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EACtC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAClB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACpD,SAAS,WAAW,KAClB,OAAO,CAAC,IAAI,CA6Dd,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAClB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9C,SAAS,WAAW,KAClB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CA+DlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,QAAQ,CAAC,CAAC,CAAC,EAClB,aAAa,MAAM,EACnB,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC9C,SAAS,WAAW,KAClB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAsExC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,cAAc;;gBAId,OAAO,EAAE,MAAM;IAO3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxB,OAAO,IAAI,IAAI;CAQf"}

package/dist/async.js

@@ -7,7 +7,7 @@ export const wait = (duration = 0) => new Promise((resolve) => setTimeout(resolv
  */
 export const is_promise = (value) => value != null && typeof value.then === 'function';
 /**
- * Creates a object with a `promise` and its `resolve`/`reject` handlers.
+ * Creates an object with a `promise` and its `resolve`/`reject` handlers.
  */
 export const create_deferred = () => {
     let resolve;
@@ -19,108 +19,142 @@ export const create_deferred = () => {
     return { promise, resolve, reject };
 };
 /**
- * Runs an async function on each item with controlled concurrency.
+ * Runs a function on each item with controlled concurrency.
  * Like `map_concurrent` but doesn't collect results (more efficient for side effects).
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  *
  * @example
  * ```ts
  * await each_concurrent(
  *   file_paths,
- *   async (path) => { await unlink(path); },
  *   5, // max 5 concurrent deletions
+ *   async (path) => { await unlink(path); },
  * );
  * ```
  */
-export const each_concurrent = async (items, fn, concurrency) => {
-    if (concurrency < 1) {
+export const each_concurrent = async (items, concurrency, fn, signal) => {
+    if (!(concurrency >= 1)) {
         throw new Error('concurrency must be at least 1');
     }
+    const iterator = items[Symbol.iterator]();
     let next_index = 0;
     let active_count = 0;
     let rejected = false;
     return new Promise((resolve, reject) => {
-        const run_next = () => {
-            // Stop spawning if we've rejected
+        const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+        const done = () => {
+            cleanup?.();
+            resolve();
+        };
+        const fail = (error) => {
             if (rejected)
                 return;
-            // Check if we're done
-            if (next_index >= items.length && active_count === 0) {
-                resolve();
+            rejected = true;
+            cleanup?.();
+            reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+        };
+        function on_abort() {
+            fail(signal.reason);
+        }
+        if (signal?.aborted) {
+            fail(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', on_abort);
+        const run_next = () => {
+            if (rejected)
                 return;
-            }
             // Spawn workers up to concurrency limit
-            while (active_count < concurrency && next_index < items.length) {
+            while (active_count < concurrency) {
+                const next = iterator.next();
+                if (next.done) {
+                    if (active_count === 0)
+                        done();
+                    return;
+                }
                 const index = next_index++;
-                const item = items[index];
+                const item = next.value;
                 active_count++;
-                fn(item, index)
+                new Promise((r) => r(fn(item, index)))
                     .then(() => {
                     if (rejected)
                         return;
                     active_count--;
                     run_next();
                 })
-                    .catch((error) => {
-                    if (rejected)
-                        return;
-                    rejected = true;
-                    reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
-                });
+                    .catch(fail);
             }
         };
-        // Handle empty array
-        if (items.length === 0) {
-            resolve();
-            return;
-        }
         run_next();
     });
 };
 /**
  * Maps over items with controlled concurrency, preserving input order.
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of results in same order as input
  *
  * @example
  * ```ts
  * const results = await map_concurrent(
  *   file_paths,
- *   async (path) => readFile(path, 'utf8'),
  *   5, // max 5 concurrent reads
+ *   async (path) => readFile(path, 'utf8'),
  * );
  * ```
  */
-export const map_concurrent = async (items, fn, concurrency) => {
-    if (concurrency < 1) {
+export const map_concurrent = async (items, concurrency, fn, signal) => {
+    if (!(concurrency >= 1)) {
         throw new Error('concurrency must be at least 1');
     }
-    const results = new Array(items.length);
+    const results = [];
+    const iterator = items[Symbol.iterator]();
     let next_index = 0;
     let active_count = 0;
     let rejected = false;
     return new Promise((resolve, reject) => {
-        const run_next = () => {
-            // Stop spawning if we've rejected
+        const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+        const done = () => {
+            cleanup?.();
+            resolve(results);
+        };
+        const fail = (error) => {
             if (rejected)
                 return;
-            // Check if we're done
-            if (next_index >= items.length && active_count === 0) {
-                resolve(results);
+            rejected = true;
+            cleanup?.();
+            reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+        };
+        function on_abort() {
+            fail(signal.reason);
+        }
+        if (signal?.aborted) {
+            fail(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', on_abort);
+        const run_next = () => {
+            if (rejected)
                 return;
-            }
             // Spawn workers up to concurrency limit
-            while (active_count < concurrency && next_index < items.length) {
+            while (active_count < concurrency) {
+                const next = iterator.next();
+                if (next.done) {
+                    if (active_count === 0)
+                        done();
+                    return;
+                }
                 const index = next_index++;
-                const item = items[index];
+                const item = next.value;
                 active_count++;
-                fn(item, index)
+                new Promise((r) => r(fn(item, index)))
                     .then((result) => {
                     if (rejected)
                         return;
@@ -128,19 +162,9 @@ export const map_concurrent = async (items, fn, concurrency) => {
                     active_count--;
                     run_next();
                 })
-                    .catch((error) => {
-                    if (rejected)
-                        return;
-                    rejected = true;
-                    reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
-                });
+                    .catch(fail);
             }
         };
-        // Handle empty array
-        if (items.length === 0) {
-            resolve(results);
-            return;
-        }
         run_next();
     });
 };
@@ -148,14 +172,18 @@ export const map_concurrent = async (items, fn, concurrency) => {
  * Like `map_concurrent` but collects all results/errors instead of failing fast.
  * Returns an array of settlement objects matching the `Promise.allSettled` pattern.
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * On abort, resolves with partial results: completed items keep their real settlements,
+ * in-flight and un-started items are settled as rejected with the abort reason.
+ *
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of `PromiseSettledResult` objects in input order
  *
  * @example
  * ```ts
- * const results = await map_concurrent_settled(urls, fetch, 5);
+ * const results = await map_concurrent_settled(urls, 5, fetch);
  * for (const [i, result] of results.entries()) {
  *   if (result.status === 'fulfilled') {
  *     console.log(`${urls[i]}: ${result.value.status}`);
@@ -165,43 +193,71 @@ export const map_concurrent = async (items, fn, concurrency) => {
  * }
  * ```
  */
-export const map_concurrent_settled = async (items, fn, concurrency) => {
-    if (concurrency < 1) {
+export const map_concurrent_settled = async (items, concurrency, fn, signal) => {
+    if (!(concurrency >= 1)) {
         throw new Error('concurrency must be at least 1');
     }
-    const results = new Array(items.length);
+    const results = [];
+    const iterator = items[Symbol.iterator]();
     let next_index = 0;
     let active_count = 0;
+    let aborted = false;
     return new Promise((resolve) => {
-        const run_next = () => {
-            // Check if we're done
-            if (next_index >= items.length && active_count === 0) {
-                resolve(results);
+        const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+        const done = () => {
+            cleanup?.();
+            resolve(results);
+        };
+        function on_abort() {
+            if (aborted)
                 return;
+            aborted = true;
+            cleanup?.();
+            // Settle in-flight items as rejected with the abort reason
+            const reason = signal.reason;
+            for (let i = 0; i < next_index; i++) {
+                if (!(i in results)) {
+                    results[i] = { status: 'rejected', reason };
+                }
             }
+            resolve(results);
+        }
+        if (signal?.aborted) {
+            resolve(results);
+            return;
+        }
+        signal?.addEventListener('abort', on_abort);
+        const run_next = () => {
+            if (aborted)
+                return;
             // Spawn workers up to concurrency limit
-            while (active_count < concurrency && next_index < items.length) {
+            while (active_count < concurrency) {
+                const next = iterator.next();
+                if (next.done) {
+                    if (active_count === 0)
+                        done();
+                    return;
+                }
                 const index = next_index++;
-                const item = items[index];
+                const item = next.value;
                 active_count++;
-                fn(item, index)
+                new Promise((r) => r(fn(item, index)))
                     .then((value) => {
-                    results[index] = { status: 'fulfilled', value };
+                    if (!aborted)
+                        results[index] = { status: 'fulfilled', value };
                 })
                     .catch((reason) => {
-                    results[index] = { status: 'rejected', reason };
+                    if (!aborted)
+                        results[index] = { status: 'rejected', reason };
                 })
                     .finally(() => {
+                    if (aborted)
+                        return;
                     active_count--;
                     run_next();
                 });
             }
         };
-        // Handle empty array
-        if (items.length === 0) {
-            resolve(results);
-            return;
-        }
         run_next();
     });
 };
@@ -214,12 +270,15 @@ export class AsyncSemaphore {
     #permits;
     #waiters = [];
     constructor(permits) {
+        if (!(permits >= 0)) {
+            throw new Error('permits must be >= 0');
+        }
         this.#permits = permits;
     }
-    async acquire() {
+    acquire() {
         if (this.#permits > 0) {
             this.#permits--;
-            return;
+            return Promise.resolve();
         }
         return new Promise((resolve) => {
             this.#waiters.push(resolve);

package/dist/zod.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Zod schema introspection utilities.
+ *
+ * Generic helpers for extracting metadata from Zod schemas.
+ * Designed for CLI argument parsing but applicable elsewhere.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+/**
+ * Unwrap nested schema types (optional, default, nullable, etc).
+ *
+ * @param def - Zod type definition to unwrap.
+ * @returns Inner schema if wrapped, undefined otherwise.
+ */
+export declare const zod_to_subschema: (def: z.core.$ZodTypeDef) => z.ZodType | undefined;
+/**
+ * Get the description from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract description from.
+ * @returns Description string or null if not found.
+ */
+export declare const zod_to_schema_description: (schema: z.ZodType) => string | null;
+/**
+ * Get the default value from a schema, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract default from.
+ * @returns Default value or undefined.
+ */
+export declare const zod_to_schema_default: (schema: z.ZodType) => unknown;
+/**
+ * Get aliases from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract aliases from.
+ * @returns Array of alias strings.
+ */
+export declare const zod_to_schema_aliases: (schema: z.ZodType) => Array<string>;
+/**
+ * Get the type string for a schema, suitable for display.
+ *
+ * @param schema - Zod schema to get type string for.
+ * @returns Human-readable type string.
+ */
+export declare const zod_to_schema_type_string: (schema: z.ZodType) => string;
+/**
+ * Format a value for display in help text.
+ *
+ * @param value - Value to format.
+ * @returns Formatted string representation.
+ */
+export declare const zod_format_value: (value: unknown) => string;
+/**
+ * Property extracted from an object schema.
+ */
+export interface ZodSchemaProperty {
+    name: string;
+    type: string;
+    description: string;
+    default: unknown;
+    aliases: Array<string>;
+}
+/**
+ * Extract properties from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from.
+ * @returns Array of property definitions.
+ */
+export declare const zod_to_schema_properties: (schema: z.ZodType) => Array<ZodSchemaProperty>;
+/**
+ * Get all property names and their aliases from an object schema.
+ *
+ * @param schema - Zod object schema.
+ * @returns Set of all names and aliases.
+ */
+export declare const zod_to_schema_names_with_aliases: (schema: z.ZodType) => Set<string>;
+//# sourceMappingURL=zod.d.ts.map

package/dist/zod.d.ts.map

@@ -0,0 +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"}

package/dist/zod.js

@@ -0,0 +1,198 @@
+/**
+ * Zod schema introspection utilities.
+ *
+ * Generic helpers for extracting metadata from Zod schemas.
+ * Designed for CLI argument parsing but applicable elsewhere.
+ *
+ * @module
+ */
+//
+// Schema Introspection
+//
+/**
+ * Unwrap nested schema types (optional, default, nullable, etc).
+ *
+ * @param def - Zod type definition to unwrap.
+ * @returns Inner schema if wrapped, undefined otherwise.
+ */
+export const zod_to_subschema = (def) => {
+    if ('innerType' in def) {
+        return def.innerType;
+    }
+    else if ('in' in def) {
+        return def.in;
+    }
+    else if ('schema' in def) {
+        return def.schema;
+    }
+    return undefined;
+};
+/**
+ * Get the description from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract description from.
+ * @returns Description string or null if not found.
+ */
+export const zod_to_schema_description = (schema) => {
+    const meta = schema.meta();
+    if (meta?.description) {
+        return meta.description;
+    }
+    const subschema = zod_to_subschema(schema.def);
+    if (subschema) {
+        return zod_to_schema_description(subschema);
+    }
+    return null;
+};
+/**
+ * Get the default value from a schema, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract default from.
+ * @returns Default value or undefined.
+ */
+export const zod_to_schema_default = (schema) => {
+    const { def } = schema._zod;
+    if ('defaultValue' in def) {
+        return def.defaultValue;
+    }
+    const subschema = zod_to_subschema(def);
+    if (subschema) {
+        return zod_to_schema_default(subschema);
+    }
+    return undefined;
+};
+/**
+ * Get aliases from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract aliases from.
+ * @returns Array of alias strings.
+ */
+export const zod_to_schema_aliases = (schema) => {
+    const meta = schema.meta();
+    if (meta?.aliases) {
+        return meta.aliases;
+    }
+    const subschema = zod_to_subschema(schema.def);
+    if (subschema) {
+        return zod_to_schema_aliases(subschema);
+    }
+    return [];
+};
+/**
+ * Get the type string for a schema, suitable for display.
+ *
+ * @param schema - Zod schema to get type string for.
+ * @returns Human-readable type string.
+ */
+export const zod_to_schema_type_string = (schema) => {
+    const { def } = schema._zod;
+    switch (def.type) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'int':
+            return 'int';
+        case 'boolean':
+            return 'boolean';
+        case 'bigint':
+            return 'bigint';
+        case 'null':
+            return 'null';
+        case 'undefined':
+            return 'undefined';
+        case 'any':
+            return 'any';
+        case 'unknown':
+            return 'unknown';
+        case 'array':
+            return 'Array<string>';
+        case 'enum':
+            return schema.options
+                .map((v) => `'${v}'`)
+                .join(' | ');
+        case 'literal':
+            return def.values
+                .map((v) => zod_format_value(v))
+                .join(' | ');
+        case 'nullable': {
+            const subschema = zod_to_subschema(def);
+            return subschema ? zod_to_schema_type_string(subschema) + ' | null' : 'nullable';
+        }
+        case 'optional': {
+            const subschema = zod_to_subschema(def);
+            return subschema ? zod_to_schema_type_string(subschema) + ' | undefined' : 'optional';
+        }
+        default: {
+            const subschema = zod_to_subschema(def);
+            return subschema ? zod_to_schema_type_string(subschema) : def.type;
+        }
+    }
+};
+/**
+ * Format a value for display in help text.
+ *
+ * @param value - Value to format.
+ * @returns Formatted string representation.
+ */
+export const zod_format_value = (value) => {
+    if (value === undefined)
+        return '';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `'${value}'`;
+    if (Array.isArray(value))
+        return '[]';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return String(value);
+    return '';
+};
+/**
+ * Extract properties from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from.
+ * @returns Array of property definitions.
+ */
+export const zod_to_schema_properties = (schema) => {
+    const { def } = schema;
+    if (!('shape' in def)) {
+        return [];
+    }
+    const shape = def.shape;
+    const properties = [];
+    for (const name in shape) {
+        // Skip no- prefixed fields (used for boolean negation)
+        if ('no-' + name in shape)
+            continue;
+        const field = shape[name];
+        properties.push({
+            name,
+            type: zod_to_schema_type_string(field),
+            description: zod_to_schema_description(field) ?? '',
+            default: zod_to_schema_default(field),
+            aliases: zod_to_schema_aliases(field),
+        });
+    }
+    return properties;
+};
+/**
+ * Get all property names and their aliases from an object schema.
+ *
+ * @param schema - Zod object schema.
+ * @returns Set of all names and aliases.
+ */
+export const zod_to_schema_names_with_aliases = (schema) => {
+    const names = new Set();
+    for (const prop of zod_to_schema_properties(schema)) {
+        if (prop.name !== '_') {
+            names.add(prop.name);
+            for (const alias of prop.aliases) {
+                names.add(alias);
+            }
+        }
+    }
+    return names;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.51.0",
+  "version": "0.52.1",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -69,10 +69,10 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_code": "^0.45.0",
-    "@fuzdev/fuz_css": "^0.50.0",
-    "@fuzdev/fuz_ui": "^0.183.1",
-    "@fuzdev/gro": "^0.192.1",
+    "@fuzdev/fuz_code": "^0.45.1",
+    "@fuzdev/fuz_css": "^0.53.0",
+    "@fuzdev/fuz_ui": "^0.184.0",
+    "@fuzdev/gro": "^0.195.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
     "@sveltejs/adapter-static": "^3.0.10",

package/src/lib/async.ts

@@ -13,7 +13,7 @@ export const is_promise = (value: unknown): value is Promise<unknown> =>
 	value != null && typeof (value as Promise<unknown>).then === 'function';
 
 /**
- * Creates a deferred object with a promise and its resolve/reject handlers.
+ * A deferred object with a promise and its resolve/reject handlers.
  */
 export interface Deferred<T> {
 	promise: Promise<T>;
@@ -22,7 +22,7 @@ export interface Deferred<T> {
 }
 
 /**
- * Creates a object with a `promise` and its `resolve`/`reject` handlers.
+ * Creates an object with a `promise` and its `resolve`/`reject` handlers.
  */
 export const create_deferred = <T>(): Deferred<T> => {
 	let resolve!: (value: T) => void;
@@ -35,72 +35,87 @@ export const create_deferred = <T>(): Deferred<T> => {
 };
 
 /**
- * Runs an async function on each item with controlled concurrency.
+ * Runs a function on each item with controlled concurrency.
  * Like `map_concurrent` but doesn't collect results (more efficient for side effects).
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  *
  * @example
  * ```ts
  * await each_concurrent(
  *   file_paths,
- *   async (path) => { await unlink(path); },
  *   5, // max 5 concurrent deletions
+ *   async (path) => { await unlink(path); },
  * );
  * ```
  */
 export const each_concurrent = async <T>(
-	items: Array<T>,
-	fn: (item: T, index: number) => Promise<void>,
+	items: Iterable<T>,
 	concurrency: number,
+	fn: (item: T, index: number) => Promise<void> | void,
+	signal?: AbortSignal,
 ): Promise<void> => {
-	if (concurrency < 1) {
+	if (!(concurrency >= 1)) {
 		throw new Error('concurrency must be at least 1');
 	}
 
+	const iterator = items[Symbol.iterator]();
 	let next_index = 0;
 	let active_count = 0;
 	let rejected = false;
 
 	return new Promise((resolve, reject) => {
-		const run_next = (): void => {
-			// Stop spawning if we've rejected
+		const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+
+		const done = (): void => {
+			cleanup?.();
+			resolve();
+		};
+
+		const fail = (error: unknown): void => {
 			if (rejected) return;
+			rejected = true;
+			cleanup?.();
+			reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+		};
 
-			// Check if we're done
-			if (next_index >= items.length && active_count === 0) {
-				resolve();
-				return;
-			}
+		function on_abort(): void {
+			fail(signal!.reason);
+		}
+
+		if (signal?.aborted) {
+			fail(signal.reason);
+			return;
+		}
+		signal?.addEventListener('abort', on_abort);
+
+		const run_next = (): void => {
+			if (rejected) return;
 
 			// Spawn workers up to concurrency limit
-			while (active_count < concurrency && next_index < items.length) {
+			while (active_count < concurrency) {
+				const next = iterator.next();
+				if (next.done) {
+					if (active_count === 0) done();
+					return;
+				}
 				const index = next_index++;
-				const item = items[index]!;
+				const item = next.value;
 				active_count++;
 
-				fn(item, index)
+				new Promise<void>((r) => r(fn(item, index)))
 					.then(() => {
 						if (rejected) return;
 						active_count--;
 						run_next();
 					})
-					.catch((error) => {
-						if (rejected) return;
-						rejected = true;
-						reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
-					});
+					.catch(fail);
 			}
 		};
 
-		// Handle empty array
-		if (items.length === 0) {
-			resolve();
-			return;
-		}
-
 		run_next();
 	});
 };
@@ -108,72 +123,87 @@ export const each_concurrent = async <T>(
 /**
  * Maps over items with controlled concurrency, preserving input order.
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of results in same order as input
  *
  * @example
  * ```ts
  * const results = await map_concurrent(
  *   file_paths,
- *   async (path) => readFile(path, 'utf8'),
  *   5, // max 5 concurrent reads
+ *   async (path) => readFile(path, 'utf8'),
  * );
  * ```
  */
 export const map_concurrent = async <T, R>(
-	items: Array<T>,
-	fn: (item: T, index: number) => Promise<R>,
+	items: Iterable<T>,
 	concurrency: number,
+	fn: (item: T, index: number) => Promise<R> | R,
+	signal?: AbortSignal,
 ): Promise<Array<R>> => {
-	if (concurrency < 1) {
+	if (!(concurrency >= 1)) {
 		throw new Error('concurrency must be at least 1');
 	}
 
-	const results: Array<R> = new Array(items.length);
+	const results: Array<R> = [];
+	const iterator = items[Symbol.iterator]();
 	let next_index = 0;
 	let active_count = 0;
 	let rejected = false;
 
 	return new Promise((resolve, reject) => {
-		const run_next = (): void => {
-			// Stop spawning if we've rejected
+		const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+
+		const done = (): void => {
+			cleanup?.();
+			resolve(results);
+		};
+
+		const fail = (error: unknown): void => {
 			if (rejected) return;
+			rejected = true;
+			cleanup?.();
+			reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+		};
 
-			// Check if we're done
-			if (next_index >= items.length && active_count === 0) {
-				resolve(results);
-				return;
-			}
+		function on_abort(): void {
+			fail(signal!.reason);
+		}
+
+		if (signal?.aborted) {
+			fail(signal.reason);
+			return;
+		}
+		signal?.addEventListener('abort', on_abort);
+
+		const run_next = (): void => {
+			if (rejected) return;
 
 			// Spawn workers up to concurrency limit
-			while (active_count < concurrency && next_index < items.length) {
+			while (active_count < concurrency) {
+				const next = iterator.next();
+				if (next.done) {
+					if (active_count === 0) done();
+					return;
+				}
 				const index = next_index++;
-				const item = items[index]!;
+				const item = next.value;
 				active_count++;
 
-				fn(item, index)
+				new Promise<R>((r) => r(fn(item, index)))
 					.then((result) => {
 						if (rejected) return;
 						results[index] = result;
 						active_count--;
 						run_next();
 					})
-					.catch((error) => {
-						if (rejected) return;
-						rejected = true;
-						reject(error); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
-					});
+					.catch(fail);
 			}
 		};
 
-		// Handle empty array
-		if (items.length === 0) {
-			resolve(results);
-			return;
-		}
-
 		run_next();
 	});
 };
@@ -182,14 +212,18 @@ export const map_concurrent = async <T, R>(
  * Like `map_concurrent` but collects all results/errors instead of failing fast.
  * Returns an array of settlement objects matching the `Promise.allSettled` pattern.
  *
- * @param items array of items to process
- * @param fn async function to apply to each item
+ * On abort, resolves with partial results: completed items keep their real settlements,
+ * in-flight and un-started items are settled as rejected with the abort reason.
+ *
+ * @param items items to process
  * @param concurrency maximum number of concurrent operations
+ * @param fn function to apply to each item
+ * @param signal optional `AbortSignal` to cancel processing
  * @returns promise resolving to array of `PromiseSettledResult` objects in input order
  *
  * @example
  * ```ts
- * const results = await map_concurrent_settled(urls, fetch, 5);
+ * const results = await map_concurrent_settled(urls, 5, fetch);
  * for (const [i, result] of results.entries()) {
  *   if (result.status === 'fulfilled') {
  *     console.log(`${urls[i]}: ${result.value.status}`);
@@ -200,52 +234,78 @@ export const map_concurrent = async <T, R>(
  * ```
  */
 export const map_concurrent_settled = async <T, R>(
-	items: Array<T>,
-	fn: (item: T, index: number) => Promise<R>,
+	items: Iterable<T>,
 	concurrency: number,
+	fn: (item: T, index: number) => Promise<R> | R,
+	signal?: AbortSignal,
 ): Promise<Array<PromiseSettledResult<R>>> => {
-	if (concurrency < 1) {
+	if (!(concurrency >= 1)) {
 		throw new Error('concurrency must be at least 1');
 	}
 
-	const results: Array<PromiseSettledResult<R>> = new Array(items.length);
+	const results: Array<PromiseSettledResult<R>> = [];
+	const iterator = items[Symbol.iterator]();
 	let next_index = 0;
 	let active_count = 0;
+	let aborted = false;
 
 	return new Promise((resolve) => {
-		const run_next = (): void => {
-			// Check if we're done
-			if (next_index >= items.length && active_count === 0) {
-				resolve(results);
-				return;
+		const cleanup = signal ? () => signal.removeEventListener('abort', on_abort) : undefined;
+
+		const done = (): void => {
+			cleanup?.();
+			resolve(results);
+		};
+
+		function on_abort(): void {
+			if (aborted) return;
+			aborted = true;
+			cleanup?.();
+			// Settle in-flight items as rejected with the abort reason
+			const reason: unknown = signal!.reason;
+			for (let i = 0; i < next_index; i++) {
+				if (!(i in results)) {
+					results[i] = {status: 'rejected', reason};
+				}
 			}
+			resolve(results);
+		}
+
+		if (signal?.aborted) {
+			resolve(results);
+			return;
+		}
+		signal?.addEventListener('abort', on_abort);
+
+		const run_next = (): void => {
+			if (aborted) return;
 
 			// Spawn workers up to concurrency limit
-			while (active_count < concurrency && next_index < items.length) {
+			while (active_count < concurrency) {
+				const next = iterator.next();
+				if (next.done) {
+					if (active_count === 0) done();
+					return;
+				}
 				const index = next_index++;
-				const item = items[index]!;
+				const item = next.value;
 				active_count++;
 
-				fn(item, index)
+				new Promise<R>((r) => r(fn(item, index)))
 					.then((value) => {
-						results[index] = {status: 'fulfilled', value};
+						if (!aborted) results[index] = {status: 'fulfilled', value};
 					})
 					.catch((reason: unknown) => {
-						results[index] = {status: 'rejected', reason};
+						if (!aborted) results[index] = {status: 'rejected', reason};
 					})
 					.finally(() => {
+						if (aborted) return;
 						active_count--;
 						run_next();
 					});
 			}
 		};
 
-		// Handle empty array
-		if (items.length === 0) {
-			resolve(results);
-			return;
-		}
-
 		run_next();
 	});
 };
@@ -260,13 +320,16 @@ export class AsyncSemaphore {
 	#waiters: Array<() => void> = [];
 
 	constructor(permits: number) {
+		if (!(permits >= 0)) {
+			throw new Error('permits must be >= 0');
+		}
 		this.#permits = permits;
 	}
 
-	async acquire(): Promise<void> {
+	acquire(): Promise<void> {
 		if (this.#permits > 0) {
 			this.#permits--;
-			return;
+			return Promise.resolve();
 		}
 		return new Promise<void>((resolve) => {
 			this.#waiters.push(resolve);

package/src/lib/zod.ts

@@ -0,0 +1,218 @@
+/**
+ * Zod schema introspection utilities.
+ *
+ * Generic helpers for extracting metadata from Zod schemas.
+ * Designed for CLI argument parsing but applicable elsewhere.
+ *
+ * @module
+ */
+
+import type {z} from 'zod';
+
+//
+// Schema Introspection
+//
+
+/**
+ * Unwrap nested schema types (optional, default, nullable, etc).
+ *
+ * @param def - Zod type definition to unwrap.
+ * @returns Inner schema if wrapped, undefined otherwise.
+ */
+export const zod_to_subschema = (def: z.core.$ZodTypeDef): z.ZodType | undefined => {
+	if ('innerType' in def) {
+		return def.innerType as z.ZodType;
+	} else if ('in' in def) {
+		return def.in as z.ZodType;
+	} else if ('schema' in def) {
+		return def.schema as z.ZodType;
+	}
+	return undefined;
+};
+
+/**
+ * Get the description from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract description from.
+ * @returns Description string or null if not found.
+ */
+export const zod_to_schema_description = (schema: z.ZodType): string | null => {
+	const meta = schema.meta();
+	if (meta?.description) {
+		return meta.description;
+	}
+	const subschema = zod_to_subschema(schema.def);
+	if (subschema) {
+		return zod_to_schema_description(subschema);
+	}
+	return null;
+};
+
+/**
+ * Get the default value from a schema, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract default from.
+ * @returns Default value or undefined.
+ */
+export const zod_to_schema_default = (schema: z.ZodType): unknown => {
+	const {def} = schema._zod;
+	if ('defaultValue' in def) {
+		return def.defaultValue;
+	}
+	const subschema = zod_to_subschema(def);
+	if (subschema) {
+		return zod_to_schema_default(subschema);
+	}
+	return undefined;
+};
+
+/**
+ * Get aliases from a schema's metadata, unwrapping if needed.
+ *
+ * @param schema - Zod schema to extract aliases from.
+ * @returns Array of alias strings.
+ */
+export const zod_to_schema_aliases = (schema: z.ZodType): Array<string> => {
+	const meta = schema.meta();
+	if (meta?.aliases) {
+		return meta.aliases as Array<string>;
+	}
+	const subschema = zod_to_subschema(schema.def);
+	if (subschema) {
+		return zod_to_schema_aliases(subschema);
+	}
+	return [];
+};
+
+/**
+ * Get the type string for a schema, suitable for display.
+ *
+ * @param schema - Zod schema to get type string for.
+ * @returns Human-readable type string.
+ */
+export const zod_to_schema_type_string = (schema: z.ZodType): string => {
+	const {def} = schema._zod;
+	switch (def.type) {
+		case 'string':
+			return 'string';
+		case 'number':
+			return 'number';
+		case 'int':
+			return 'int';
+		case 'boolean':
+			return 'boolean';
+		case 'bigint':
+			return 'bigint';
+		case 'null':
+			return 'null';
+		case 'undefined':
+			return 'undefined';
+		case 'any':
+			return 'any';
+		case 'unknown':
+			return 'unknown';
+		case 'array':
+			return 'Array<string>';
+		case 'enum':
+			return (schema as unknown as {options: Array<string>}).options
+				.map((v) => `'${v}'`)
+				.join(' | ');
+		case 'literal':
+			return (def as unknown as {values: Array<unknown>}).values
+				.map((v) => zod_format_value(v))
+				.join(' | ');
+		case 'nullable': {
+			const subschema = zod_to_subschema(def);
+			return subschema ? zod_to_schema_type_string(subschema) + ' | null' : 'nullable';
+		}
+		case 'optional': {
+			const subschema = zod_to_subschema(def);
+			return subschema ? zod_to_schema_type_string(subschema) + ' | undefined' : 'optional';
+		}
+		default: {
+			const subschema = zod_to_subschema(def);
+			return subschema ? zod_to_schema_type_string(subschema) : def.type;
+		}
+	}
+};
+
+/**
+ * Format a value for display in help text.
+ *
+ * @param value - Value to format.
+ * @returns Formatted string representation.
+ */
+export const zod_format_value = (value: unknown): string => {
+	if (value === undefined) return '';
+	if (value === null) return 'null';
+	if (typeof value === 'string') return `'${value}'`;
+	if (Array.isArray(value)) return '[]';
+	if (typeof value === 'object') return JSON.stringify(value);
+	if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+	return '';
+};
+
+//
+// Object Schema Helpers
+//
+
+/**
+ * Property extracted from an object schema.
+ */
+export interface ZodSchemaProperty {
+	name: string;
+	type: string;
+	description: string;
+	default: unknown;
+	aliases: Array<string>;
+}
+
+/**
+ * Extract properties from a Zod object schema.
+ *
+ * @param schema - Zod object schema to extract from.
+ * @returns Array of property definitions.
+ */
+export const zod_to_schema_properties = (schema: z.ZodType): Array<ZodSchemaProperty> => {
+	const {def} = schema;
+
+	if (!('shape' in def)) {
+		return [];
+	}
+	const shape = (def as z.core.$ZodObjectDef).shape;
+
+	const properties: Array<ZodSchemaProperty> = [];
+	for (const name in shape) {
+		// Skip no- prefixed fields (used for boolean negation)
+		if ('no-' + name in shape) continue;
+
+		const field = shape[name] as z.ZodType;
+		properties.push({
+			name,
+			type: zod_to_schema_type_string(field),
+			description: zod_to_schema_description(field) ?? '',
+			default: zod_to_schema_default(field),
+			aliases: zod_to_schema_aliases(field),
+		});
+	}
+	return properties;
+};
+
+/**
+ * Get all property names and their aliases from an object schema.
+ *
+ * @param schema - Zod object schema.
+ * @returns Set of all names and aliases.
+ */
+export const zod_to_schema_names_with_aliases = (schema: z.ZodType): Set<string> => {
+	const names: Set<string> = new Set();
+	for (const prop of zod_to_schema_properties(schema)) {
+		if (prop.name !== '_') {
+			names.add(prop.name);
+			for (const alias of prop.aliases) {
+				names.add(alias);
+			}
+		}
+	}
+	return names;
+};