@dbx-tools/shared-core 0.3.44 → 0.4.0

package/lib/src/predicate.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Fluent, callable predicate combinators that preserve TypeScript type guards.
+ *
+ * A Predicate<T, U> is:
+ * - Callable as `(value: T) => value is U`
+ * - Composable through `.and()`, `.or()`, and `.negate()`
+ *
+ * Ordinary boolean predicates are treated as narrowing to `T`, meaning they
+ * do not narrow the input type by themselves. Composed predicates passed to
+ * `.and()` / `.or()` may return any value; they are tested for truthiness.
+ *
+ * @module
+ */
+/** An ordinary boolean predicate. */
+export type PredicateFunction<T> = (value: T) => boolean;
+/** A predicate that narrows T to U. */
+export type TypePredicateFunction<T, U extends T> = (value: T) => value is U;
+/** A predicate tested for truthiness when composed with `.and()` / `.or()`. */
+export type PredicateInput<T> = (value: T) => unknown;
+/**
+ * Extracts the narrowed type from a type predicate.
+ *
+ * Ordinary boolean predicates do not narrow, so they produce T. A guard whose
+ * narrowed type is disjoint from T (`Extract<U, T>` is `never`) is treated as a
+ * non-narrowing filter and keeps T, rather than collapsing the chain to `never` -
+ * this is what a negated narrowing guard looks like (e.g. `hasName(...).negate()`,
+ * which widens back to a supertype of T).
+ */
+type NarrowedBy<T, P> = P extends (value: any) => value is infer U ? [Extract<U, T>] extends [never] ? T : Extract<U, T> : T;
+/** Intersects the narrowed types produced by a tuple of predicates. */
+type AndNarrowed<T, P extends readonly PredicateInput<T>[], Result = T> = P extends readonly [
+    infer First,
+    ...infer Rest extends readonly PredicateInput<T>[]
+] ? AndNarrowed<T, Rest, Result & NarrowedBy<T, First>> : Result;
+/** Unions the narrowed types produced by a tuple of predicates. */
+type OrNarrowed<T, P extends readonly PredicateInput<T>[], Result = never> = P extends readonly [
+    infer First,
+    ...infer Rest extends readonly PredicateInput<T>[]
+] ? OrNarrowed<T, Rest, Result | NarrowedBy<T, First>> : Result;
+/**
+ * A callable predicate with fluent composition methods.
+ *
+ * T is the accepted input type.
+ * U is the type established when the predicate returns true.
+ */
+export interface Predicate<T, U extends T = T> {
+    (value: T): value is U;
+    /**
+     * Returns a predicate requiring this predicate and every supplied predicate
+     * to match.
+     *
+     * Type guards are intersected. Additional predicates are checked against the
+     * type already established by this predicate.
+     */
+    and<const P extends readonly PredicateInput<U>[]>(...predicates: P): Predicate<T, Extract<U & AndNarrowed<U, P>, T>>;
+    /**
+     * Returns a predicate requiring this predicate or any supplied predicate
+     * to match.
+     *
+     * Type guards are unioned. Because an ordinary boolean predicate could
+     * accept any value of `U`, including one causes the resulting predicate to
+     * narrow only to `U`.
+     */
+    or<const P extends readonly PredicateInput<U>[]>(...predicates: P): Predicate<T, Extract<U | OrNarrowed<U, P>, T>>;
+    /**
+     * Returns the logical inverse of this predicate.
+     *
+     * For a type predicate narrowing T to U, the result narrows to
+     * Exclude<T, U>.
+     */
+    negate(): Predicate<T, Exclude<T, U>>;
+}
+/**
+ * Wraps a type predicate while preserving its narrowed type.
+ */
+export declare function create<T, U extends T>(predicate: TypePredicateFunction<T, U>): Predicate<T, U>;
+/**
+ * Wraps an ordinary boolean or truthy predicate.
+ */
+export declare function create<T>(predicate: PredicateInput<T>): Predicate<T, T>;
+export {};

package/lib/src/predicate.js

@@ -0,0 +1,43 @@
+/**
+ * Fluent, callable predicate combinators that preserve TypeScript type guards.
+ *
+ * A Predicate<T, U> is:
+ * - Callable as `(value: T) => value is U`
+ * - Composable through `.and()`, `.or()`, and `.negate()`
+ *
+ * Ordinary boolean predicates are treated as narrowing to `T`, meaning they
+ * do not narrow the input type by themselves. Composed predicates passed to
+ * `.and()` / `.or()` may return any value; they are tested for truthiness.
+ *
+ * @module
+ */
+/** Coerce a predicate result to boolean the way `if (...)` does. */
+function isTruthy(test) {
+    return (value) => Boolean(test(value));
+}
+/**
+ * Creates the callable predicate object.
+ *
+ * The public generic behavior is provided by Predicate<T, U>. Runtime
+ * composition coerces predicate results to boolean; type predicates are
+ * ordinary boolean functions at runtime.
+ */
+function buildPredicate(test) {
+    const check = isTruthy(test);
+    const callable = ((value) => check(value));
+    return Object.assign(callable, {
+        and(...predicates) {
+            return buildPredicate((value) => check(value) && predicates.every((predicate) => isTruthy(predicate)(value)));
+        },
+        or(...predicates) {
+            return buildPredicate((value) => check(value) || predicates.some((predicate) => isTruthy(predicate)(value)));
+        },
+        negate() {
+            return buildPredicate((value) => !check(value));
+        },
+    });
+}
+export function create(predicate) {
+    return buildPredicate(predicate);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJlZGljYXRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3ByZWRpY2F0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7O0dBWUc7QUFtRkgsb0VBQW9FO0FBQ3BFLFNBQVMsUUFBUSxDQUFJLElBQTJCO0lBQzlDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQztBQUN6QyxDQUFDO0FBRUQ7Ozs7OztHQU1HO0FBQ0gsU0FBUyxjQUFjLENBQWlCLElBQTJCO0lBQ2pFLE1BQU0sS0FBSyxHQUFHLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUM3QixNQUFNLFFBQVEsR0FBRyxDQUFDLENBQUMsS0FBUSxFQUFjLEVBQUUsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLENBQTZCLENBQUM7SUFFdEYsT0FBTyxNQUFNLENBQUMsTUFBTSxDQUFDLFFBQVEsRUFBRTtRQUM3QixHQUFHLENBQ0QsR0FBRyxVQUFhO1lBR2hCLE9BQU8sY0FBYyxDQUNuQixDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxJQUFJLFVBQVUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRSxDQUFDLFFBQVEsQ0FBQyxTQUFTLENBQUMsQ0FBQyxLQUFVLENBQUMsQ0FBQyxDQUM1RixDQUFDO1FBQ0osQ0FBQztRQUVELEVBQUUsQ0FDQSxHQUFHLFVBQWE7WUFHaEIsT0FBTyxjQUFjLENBQ25CLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLElBQUksVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDLFNBQVMsRUFBRSxFQUFFLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxDQUFDLEtBQVUsQ0FBQyxDQUFDLENBQzNGLENBQUM7UUFDSixDQUFDO1FBRUQsTUFBTTtZQUNKLE9BQU8sY0FBYyxDQUFtQixDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQztRQUNwRSxDQUFDO0tBQ0YsQ0FBb0IsQ0FBQztBQUN4QixDQUFDO0FBWUQsTUFBTSxVQUFVLE1BQU0sQ0FDcEIsU0FBMEQ7SUFFMUQsT0FBTyxjQUFjLENBQU8sU0FBUyxDQUFDLENBQUM7QUFDekMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogRmx1ZW50LCBjYWxsYWJsZSBwcmVkaWNhdGUgY29tYmluYXRvcnMgdGhhdCBwcmVzZXJ2ZSBUeXBlU2NyaXB0IHR5cGUgZ3VhcmRzLlxuICpcbiAqIEEgUHJlZGljYXRlPFQsIFU+IGlzOlxuICogLSBDYWxsYWJsZSBhcyBgKHZhbHVlOiBUKSA9PiB2YWx1ZSBpcyBVYFxuICogLSBDb21wb3NhYmxlIHRocm91Z2ggYC5hbmQoKWAsIGAub3IoKWAsIGFuZCBgLm5lZ2F0ZSgpYFxuICpcbiAqIE9yZGluYXJ5IGJvb2xlYW4gcHJlZGljYXRlcyBhcmUgdHJlYXRlZCBhcyBuYXJyb3dpbmcgdG8gYFRgLCBtZWFuaW5nIHRoZXlcbiAqIGRvIG5vdCBuYXJyb3cgdGhlIGlucHV0IHR5cGUgYnkgdGhlbXNlbHZlcy4gQ29tcG9zZWQgcHJlZGljYXRlcyBwYXNzZWQgdG9cbiAqIGAuYW5kKClgIC8gYC5vcigpYCBtYXkgcmV0dXJuIGFueSB2YWx1ZTsgdGhleSBhcmUgdGVzdGVkIGZvciB0cnV0aGluZXNzLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG4vKiogQW4gb3JkaW5hcnkgYm9vbGVhbiBwcmVkaWNhdGUuICovXG5leHBvcnQgdHlwZSBQcmVkaWNhdGVGdW5jdGlvbjxUPiA9ICh2YWx1ZTogVCkgPT4gYm9vbGVhbjtcblxuLyoqIEEgcHJlZGljYXRlIHRoYXQgbmFycm93cyBUIHRvIFUuICovXG5leHBvcnQgdHlwZSBUeXBlUHJlZGljYXRlRnVuY3Rpb248VCwgVSBleHRlbmRzIFQ+ID0gKHZhbHVlOiBUKSA9PiB2YWx1ZSBpcyBVO1xuXG4vKiogQSBwcmVkaWNhdGUgdGVzdGVkIGZvciB0cnV0aGluZXNzIHdoZW4gY29tcG9zZWQgd2l0aCBgLmFuZCgpYCAvIGAub3IoKWAuICovXG5leHBvcnQgdHlwZSBQcmVkaWNhdGVJbnB1dDxUPiA9ICh2YWx1ZTogVCkgPT4gdW5rbm93bjtcblxuLyoqXG4gKiBFeHRyYWN0cyB0aGUgbmFycm93ZWQgdHlwZSBmcm9tIGEgdHlwZSBwcmVkaWNhdGUuXG4gKlxuICogT3JkaW5hcnkgYm9vbGVhbiBwcmVkaWNhdGVzIGRvIG5vdCBuYXJyb3csIHNvIHRoZXkgcHJvZHVjZSBULiBBIGd1YXJkIHdob3NlXG4gKiBuYXJyb3dlZCB0eXBlIGlzIGRpc2pvaW50IGZyb20gVCAoYEV4dHJhY3Q8VSwgVD5gIGlzIGBuZXZlcmApIGlzIHRyZWF0ZWQgYXMgYVxuICogbm9uLW5hcnJvd2luZyBmaWx0ZXIgYW5kIGtlZXBzIFQsIHJhdGhlciB0aGFuIGNvbGxhcHNpbmcgdGhlIGNoYWluIHRvIGBuZXZlcmAgLVxuICogdGhpcyBpcyB3aGF0IGEgbmVnYXRlZCBuYXJyb3dpbmcgZ3VhcmQgbG9va3MgbGlrZSAoZS5nLiBgaGFzTmFtZSguLi4pLm5lZ2F0ZSgpYCxcbiAqIHdoaWNoIHdpZGVucyBiYWNrIHRvIGEgc3VwZXJ0eXBlIG9mIFQpLlxuICovXG50eXBlIE5hcnJvd2VkQnk8VCwgUD4gPSBQIGV4dGVuZHMgKHZhbHVlOiBhbnkpID0+IHZhbHVlIGlzIGluZmVyIFVcbiAgPyBbRXh0cmFjdDxVLCBUPl0gZXh0ZW5kcyBbbmV2ZXJdXG4gICAgPyBUXG4gICAgOiBFeHRyYWN0PFUsIFQ+XG4gIDogVDtcblxuLyoqIEludGVyc2VjdHMgdGhlIG5hcnJvd2VkIHR5cGVzIHByb2R1Y2VkIGJ5IGEgdHVwbGUgb2YgcHJlZGljYXRlcy4gKi9cbnR5cGUgQW5kTmFycm93ZWQ8VCwgUCBleHRlbmRzIHJlYWRvbmx5IFByZWRpY2F0ZUlucHV0PFQ+W10sIFJlc3VsdCA9IFQ+ID0gUCBleHRlbmRzIHJlYWRvbmx5IFtcbiAgaW5mZXIgRmlyc3QsXG4gIC4uLmluZmVyIFJlc3QgZXh0ZW5kcyByZWFkb25seSBQcmVkaWNhdGVJbnB1dDxUPltdLFxuXVxuICA/IEFuZE5hcnJvd2VkPFQsIFJlc3QsIFJlc3VsdCAmIE5hcnJvd2VkQnk8VCwgRmlyc3Q+PlxuICA6IFJlc3VsdDtcblxuLyoqIFVuaW9ucyB0aGUgbmFycm93ZWQgdHlwZXMgcHJvZHVjZWQgYnkgYSB0dXBsZSBvZiBwcmVkaWNhdGVzLiAqL1xudHlwZSBPck5hcnJvd2VkPFQsIFAgZXh0ZW5kcyByZWFkb25seSBQcmVkaWNhdGVJbnB1dDxUPltdLCBSZXN1bHQgPSBuZXZlcj4gPSBQIGV4dGVuZHMgcmVhZG9ubHkgW1xuICBpbmZlciBGaXJzdCxcbiAgLi4uaW5mZXIgUmVzdCBleHRlbmRzIHJlYWRvbmx5IFByZWRpY2F0ZUlucHV0PFQ+W10sXG5dXG4gID8gT3JOYXJyb3dlZDxULCBSZXN0LCBSZXN1bHQgfCBOYXJyb3dlZEJ5PFQsIEZpcnN0Pj5cbiAgOiBSZXN1bHQ7XG5cbi8qKlxuICogQSBjYWxsYWJsZSBwcmVkaWNhdGUgd2l0aCBmbHVlbnQgY29tcG9zaXRpb24gbWV0aG9kcy5cbiAqXG4gKiBUIGlzIHRoZSBhY2NlcHRlZCBpbnB1dCB0eXBlLlxuICogVSBpcyB0aGUgdHlwZSBlc3RhYmxpc2hlZCB3aGVuIHRoZSBwcmVkaWNhdGUgcmV0dXJucyB0cnVlLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIFByZWRpY2F0ZTxULCBVIGV4dGVuZHMgVCA9IFQ+IHtcbiAgKHZhbHVlOiBUKTogdmFsdWUgaXMgVTtcblxuICAvKipcbiAgICogUmV0dXJucyBhIHByZWRpY2F0ZSByZXF1aXJpbmcgdGhpcyBwcmVkaWNhdGUgYW5kIGV2ZXJ5IHN1cHBsaWVkIHByZWRpY2F0ZVxuICAgKiB0byBtYXRjaC5cbiAgICpcbiAgICogVHlwZSBndWFyZHMgYXJlIGludGVyc2VjdGVkLiBBZGRpdGlvbmFsIHByZWRpY2F0ZXMgYXJlIGNoZWNrZWQgYWdhaW5zdCB0aGVcbiAgICogdHlwZSBhbHJlYWR5IGVzdGFibGlzaGVkIGJ5IHRoaXMgcHJlZGljYXRlLlxuICAgKi9cbiAgYW5kPGNvbnN0IFAgZXh0ZW5kcyByZWFkb25seSBQcmVkaWNhdGVJbnB1dDxVPltdPihcbiAgICAuLi5wcmVkaWNhdGVzOiBQXG4gICk6IFByZWRpY2F0ZTxULCBFeHRyYWN0PFUgJiBBbmROYXJyb3dlZDxVLCBQPiwgVD4+O1xuXG4gIC8qKlxuICAgKiBSZXR1cm5zIGEgcHJlZGljYXRlIHJlcXVpcmluZyB0aGlzIHByZWRpY2F0ZSBvciBhbnkgc3VwcGxpZWQgcHJlZGljYXRlXG4gICAqIHRvIG1hdGNoLlxuICAgKlxuICAgKiBUeXBlIGd1YXJkcyBhcmUgdW5pb25lZC4gQmVjYXVzZSBhbiBvcmRpbmFyeSBib29sZWFuIHByZWRpY2F0ZSBjb3VsZFxuICAgKiBhY2NlcHQgYW55IHZhbHVlIG9mIGBVYCwgaW5jbHVkaW5nIG9uZSBjYXVzZXMgdGhlIHJlc3VsdGluZyBwcmVkaWNhdGUgdG9cbiAgICogbmFycm93IG9ubHkgdG8gYFVgLlxuICAgKi9cbiAgb3I8Y29uc3QgUCBleHRlbmRzIHJlYWRvbmx5IFByZWRpY2F0ZUlucHV0PFU+W10+KFxuICAgIC4uLnByZWRpY2F0ZXM6IFBcbiAgKTogUHJlZGljYXRlPFQsIEV4dHJhY3Q8VSB8IE9yTmFycm93ZWQ8VSwgUD4sIFQ+PjtcblxuICAvKipcbiAgICogUmV0dXJucyB0aGUgbG9naWNhbCBpbnZlcnNlIG9mIHRoaXMgcHJlZGljYXRlLlxuICAgKlxuICAgKiBGb3IgYSB0eXBlIHByZWRpY2F0ZSBuYXJyb3dpbmcgVCB0byBVLCB0aGUgcmVzdWx0IG5hcnJvd3MgdG9cbiAgICogRXhjbHVkZTxULCBVPi5cbiAgICovXG4gIG5lZ2F0ZSgpOiBQcmVkaWNhdGU8VCwgRXhjbHVkZTxULCBVPj47XG59XG5cbi8qKiBDb2VyY2UgYSBwcmVkaWNhdGUgcmVzdWx0IHRvIGJvb2xlYW4gdGhlIHdheSBgaWYgKC4uLilgIGRvZXMuICovXG5mdW5jdGlvbiBpc1RydXRoeTxUPih0ZXN0OiAodmFsdWU6IFQpID0+IHVua25vd24pOiBQcmVkaWNhdGVGdW5jdGlvbjxUPiB7XG4gIHJldHVybiAodmFsdWUpID0+IEJvb2xlYW4odGVzdCh2YWx1ZSkpO1xufVxuXG4vKipcbiAqIENyZWF0ZXMgdGhlIGNhbGxhYmxlIHByZWRpY2F0ZSBvYmplY3QuXG4gKlxuICogVGhlIHB1YmxpYyBnZW5lcmljIGJlaGF2aW9yIGlzIHByb3ZpZGVkIGJ5IFByZWRpY2F0ZTxULCBVPi4gUnVudGltZVxuICogY29tcG9zaXRpb24gY29lcmNlcyBwcmVkaWNhdGUgcmVzdWx0cyB0byBib29sZWFuOyB0eXBlIHByZWRpY2F0ZXMgYXJlXG4gKiBvcmRpbmFyeSBib29sZWFuIGZ1bmN0aW9ucyBhdCBydW50aW1lLlxuICovXG5mdW5jdGlvbiBidWlsZFByZWRpY2F0ZTxULCBVIGV4dGVuZHMgVD4odGVzdDogKHZhbHVlOiBUKSA9PiB1bmtub3duKTogUHJlZGljYXRlPFQsIFU+IHtcbiAgY29uc3QgY2hlY2sgPSBpc1RydXRoeSh0ZXN0KTtcbiAgY29uc3QgY2FsbGFibGUgPSAoKHZhbHVlOiBUKTogdmFsdWUgaXMgVSA9PiBjaGVjayh2YWx1ZSkpIGFzICh2YWx1ZTogVCkgPT4gdmFsdWUgaXMgVTtcblxuICByZXR1cm4gT2JqZWN0LmFzc2lnbihjYWxsYWJsZSwge1xuICAgIGFuZDxjb25zdCBQIGV4dGVuZHMgcmVhZG9ubHkgUHJlZGljYXRlSW5wdXQ8VT5bXT4oXG4gICAgICAuLi5wcmVkaWNhdGVzOiBQXG4gICAgKTogUHJlZGljYXRlPFQsIEV4dHJhY3Q8VSAmIEFuZE5hcnJvd2VkPFUsIFA+LCBUPj4ge1xuICAgICAgdHlwZSBSZXN1bHQgPSBFeHRyYWN0PFUgJiBBbmROYXJyb3dlZDxVLCBQPiwgVD47XG4gICAgICByZXR1cm4gYnVpbGRQcmVkaWNhdGU8VCwgUmVzdWx0PihcbiAgICAgICAgKHZhbHVlKSA9PiBjaGVjayh2YWx1ZSkgJiYgcHJlZGljYXRlcy5ldmVyeSgocHJlZGljYXRlKSA9PiBpc1RydXRoeShwcmVkaWNhdGUpKHZhbHVlIGFzIFUpKSxcbiAgICAgICk7XG4gICAgfSxcblxuICAgIG9yPGNvbnN0IFAgZXh0ZW5kcyByZWFkb25seSBQcmVkaWNhdGVJbnB1dDxVPltdPihcbiAgICAgIC4uLnByZWRpY2F0ZXM6IFBcbiAgICApOiBQcmVkaWNhdGU8VCwgRXh0cmFjdDxVIHwgT3JOYXJyb3dlZDxVLCBQPiwgVD4+IHtcbiAgICAgIHR5cGUgUmVzdWx0ID0gRXh0cmFjdDxVIHwgT3JOYXJyb3dlZDxVLCBQPiwgVD47XG4gICAgICByZXR1cm4gYnVpbGRQcmVkaWNhdGU8VCwgUmVzdWx0PihcbiAgICAgICAgKHZhbHVlKSA9PiBjaGVjayh2YWx1ZSkgfHwgcHJlZGljYXRlcy5zb21lKChwcmVkaWNhdGUpID0+IGlzVHJ1dGh5KHByZWRpY2F0ZSkodmFsdWUgYXMgVSkpLFxuICAgICAgKTtcbiAgICB9LFxuXG4gICAgbmVnYXRlKCk6IFByZWRpY2F0ZTxULCBFeGNsdWRlPFQsIFU+PiB7XG4gICAgICByZXR1cm4gYnVpbGRQcmVkaWNhdGU8VCwgRXhjbHVkZTxULCBVPj4oKHZhbHVlKSA9PiAhY2hlY2sodmFsdWUpKTtcbiAgICB9LFxuICB9KSBhcyBQcmVkaWNhdGU8VCwgVT47XG59XG5cbi8qKlxuICogV3JhcHMgYSB0eXBlIHByZWRpY2F0ZSB3aGlsZSBwcmVzZXJ2aW5nIGl0cyBuYXJyb3dlZCB0eXBlLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY3JlYXRlPFQsIFUgZXh0ZW5kcyBUPihwcmVkaWNhdGU6IFR5cGVQcmVkaWNhdGVGdW5jdGlvbjxULCBVPik6IFByZWRpY2F0ZTxULCBVPjtcblxuLyoqXG4gKiBXcmFwcyBhbiBvcmRpbmFyeSBib29sZWFuIG9yIHRydXRoeSBwcmVkaWNhdGUuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBjcmVhdGU8VD4ocHJlZGljYXRlOiBQcmVkaWNhdGVJbnB1dDxUPik6IFByZWRpY2F0ZTxULCBUPjtcblxuZXhwb3J0IGZ1bmN0aW9uIGNyZWF0ZTxULCBVIGV4dGVuZHMgVCA9IFQ+KFxuICBwcmVkaWNhdGU6IFR5cGVQcmVkaWNhdGVGdW5jdGlvbjxULCBVPiB8IFByZWRpY2F0ZUlucHV0PFQ+LFxuKTogUHJlZGljYXRlPFQsIFU+IHtcbiAgcmV0dXJuIGJ1aWxkUHJlZGljYXRlPFQsIFU+KHByZWRpY2F0ZSk7XG59XG4iXX0=

package/lib/src/string.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Options controlling {@link tokenizeWithOptions}. All default off except
+ * `camelCase`.
+ *
+ * - `distinct` - drop duplicate tokens (first occurrence wins).
+ * - `lowerCase` - lowercase every token.
+ * - `capitalize` - upper-case each token's first letter (then
+ *   {@link TOKENIZE_OVERRIDES} fix up `ai` -> `AI` and `v2` -> `V2`).
+ * - `omitUriScheme` - strip a leading `scheme://` before tokenizing.
+ * - `omitEmailDomain` - keep only the local part of an email.
+ * - `camelCase` - split on camelCase boundaries / digit runs / acronyms
+ *   (default `true`); when `false`, split only on non-alphanumerics.
+ */
+export type TokenizeOptions = {
+    distinct?: boolean;
+    lowerCase?: boolean;
+    capitalize?: boolean;
+    omitUriScheme?: boolean;
+    omitEmailDomain?: boolean;
+    camelCase?: boolean;
+};
+export type KeyOptions = Omit<TokenizeOptions, "lowerCase" | "capitalize"> & {
+    maxLength?: number;
+    truncateStrategy?: "hash" | "trim" | "empty";
+    truncateHashLength?: number;
+};
+export type IdentifierOptions = KeyOptions & {
+    delimiter?: string;
+};
+export declare function tokenizeWithOptions(options: TokenizeOptions, ...values: unknown[]): Generator<string>;
+export declare function tokenize(...values: unknown[]): Generator<string>;
+/**
+ * Join tokenized values with `delimiter`. When the next token would push the
+ * result over `maxLength`: `trim` stops adding; `empty` returns `""`; `hash`
+ * appends a digest of accepted tokens plus the overflow token if the result
+ * still fits, otherwise `""`.
+ */
+export declare function toIdentifierWithOptions(options: IdentifierOptions, ...values: unknown[]): string;
+export declare function toIdentifier(...values: unknown[]): string;
+/**
+ * Slugified identifier: same rules as {@link toIdentifierWithOptions} with the
+ * delimiter forced to `-`. Accepts {@link KeyOptions} so callers cannot
+ * override the delimiter.
+ */
+export declare function toSlugWithOptions(options: KeyOptions, ...values: unknown[]): string;
+export declare function toSlug(...values: unknown[]): string;
+/**
+ * Trim `value` and return `null` for non-strings, `undefined`, or
+ * strings that are empty after trimming. Lets call sites collapse the
+ * common
+ *
+ * ```ts
+ * typeof v === "string" && v.trim() ? v.trim() : null
+ * ```
+ *
+ * dance into a single helper. Useful for HTTP header / query / form
+ * extractors where downstream code wants `string | null` to drive a
+ * cheap `??` / `if (x)` cascade.
+ */
+export declare function trimToNull(value: unknown): string | null;
+/**
+ * Normalize a config list that may arrive as an array or as a single
+ * comma/whitespace-separated string: split, apply `transform`, drop empties,
+ * and de-duplicate (first occurrence wins).
+ *
+ * This is the shape every allow-list / fallback-order setting in this repo
+ * takes, because the same value can come from typed config (`string[]`) or from
+ * an environment variable (`"a, b c"`). Pass `transform` to normalize entries
+ * as they are read; it defaults to trimming.
+ *
+ * @example
+ * parseList("docs.example.com, *.databricks.com");
+ * parseList(process.env.MODEL_FALLBACKS);
+ * parseList(raw, normalizeUrlPattern);
+ */
+export declare function parseList(raw: string | readonly string[] | undefined | null, transform?: (entry: string) => string): string[];
+/**
+ * {@link trimToNull} with an empty-string miss instead of `null`, for callers
+ * that build a string unconditionally and treat "absent" as "".
+ *
+ * Reading loosely-typed JSON is the motivating case: a field that should be a
+ * string may be missing or the wrong type, and the caller wants `""` rather
+ * than a null check at every access.
+ *
+ * @example
+ * const title = trimToEmpty(record.title); // always a string
+ */
+export declare function trimToEmpty(value: unknown): string;
+/**
+ * Trim the first usable string out of `value`. Returns `null` when
+ * `value` is `undefined`, `null`, an empty string, or an array whose
+ * first string member is empty. Mirrors how Express / Node header
+ * accessors expose single vs. repeated headers - the first
+ * non-empty entry wins, everything else is ignored.
+ */
+export declare function firstNonEmpty(value: unknown): string | null;
+/**
+ * Escape the five characters significant in HTML text and
+ * double-quoted attribute values (`&`, `<`, `>`, `"`, `'`) so an
+ * untrusted string can be interpolated into markup without breaking
+ * out of its context. `&` is replaced first so ampersands introduced
+ * by the later replacements aren't double-escaped.
+ */
+export declare function escapeHtml(value: string): string;
+/**
+ * Slugify `value` (using the standard {@link toIdentifierWithOptions}
+ * tokenizer + delimiter rules) and **always** suffix a short
+ * deterministic hash. Use when you need a stable, slugified id that
+ * is guaranteed to be unique across descriptions sharing the same
+ * leading tokens (tool ids, cache keys, etc.).
+ *
+ * Behaviour differs from `toIdentifierWithOptions({ maxLength,
+ * truncateStrategy: "hash" })`: that helper only appends a hash when
+ * the slug *overflows* `maxLength`. This helper appends a hash
+ * unconditionally so the result is collision-resistant even for
+ * short inputs. The hash is computed over the raw `value` so two
+ * descriptions producing the same slug still get different ids.
+ *
+ * @param value - Source string (typically a tool/agent description).
+ * @param options.delimiter - Token separator (default `"_"`).
+ * @param options.slugMaxLength - Cap on the slug portion (the part
+ *   before the hash). Default 32.
+ * @param options.hashLength - Length of the suffix produced by
+ *   {@link fnvHashWithOptions} (Crockford-style base-32 alphabet, max 7
+ *   chars). Default 6.
+ * @param options.fallbackPrefix - Prefix used when the slug is empty
+ *   (e.g. punctuation-only input). Default `"id"`.
+ */
+export declare function toUniqueSlug(value: string, options?: {
+    delimiter?: string;
+    slugMaxLength?: number;
+    hashLength?: number;
+    fallbackPrefix?: string;
+}): string;
+/**
+ * A node in the description tree consumed by {@link toDescription}.
+ *
+ * - `string` - a text paragraph.
+ * - `Description[]` - a sequence of stacked blocks at the same level
+ *   (no list markers). Plain text adjacent to a list (either direction)
+ *   flushes together so the prose reads as a lead-in or trailing
+ *   summary. Two text paragraphs, two adjacent lists, and anything
+ *   touching a map get a blank-line break.
+ * - `{ bullets: [...] }` / `{ numbered: [...] }` - explicit list. A
+ *   list of one bare string drops its marker (`-` / `1.`); a list of
+ *   one item with nested children keeps its marker as the visual anchor
+ *   for the indented children.
+ * - any other object - headers map: each key becomes a `Header:` line
+ *   followed by a blank line and the rendered value.
+ */
+export type Description = string | readonly Description[] | {
+    readonly [key: string]: Description;
+};
+/**
+ * Format a nested description tree as a Markdown-ish string suitable
+ * for an LLM system prompt, Zod `.describe()` block, Mastra tool
+ * description, or any other long-form text destination.
+ *
+ * Every string section is dedented (common leading whitespace stripped),
+ * right-trimmed line by line, and freed of leading / trailing blank
+ * lines, so callers can write multi-line template literals indented
+ * naturally in source without leaking that indentation into the
+ * consumer-facing output. Plain-string inputs flow through unchanged
+ * apart from the same normalization pass, so a single multi-line
+ * template literal works directly:
+ *
+ * ```ts
+ * toDescription(`
+ *   Ask the Genie space "${alias}" a question.
+ *   Pass the answer through as-is.
+ * `);
+ * // Ask the Genie space "default" a question.
+ * // Pass the answer through as-is.
+ *
+ * toDescription([
+ *   `
+ *     Ask the Genie space a question.
+ *     Phrase it from the user's perspective.
+ *   `,
+ *   { bullets: [
+ *     ["Pass the answer through as-is", { numbered: ["item", "item"] }],
+ *   ]},
+ *   { Instructions: "Reply with the SQL only." },
+ * ]);
+ * // Ask the Genie space a question.
+ * // Phrase it from the user's perspective.
+ * // - Pass the answer through as-is
+ * //   1. item
+ * //   2. item
+ * //
+ * // Instructions:
+ * //
+ * // Reply with the SQL only.
+ * ```
+ *
+ * See {@link Description} for the node grammar.
+ */
+export declare function toDescription(node: Description): string;
+/**
+ * Format a count with its noun, pluralizing (naive `+s`) unless the count is 1:
+ * `pluralize(1, "barrel")` -> `"1 barrel"`, `pluralize(3, "barrel")` ->
+ * `"3 barrels"`. Collapses the `${n} noun${n === 1 ? "" : "s"}` idiom.
+ */
+export declare function pluralize(count: number, noun: string): string;
+/**
+ * Title-case a snake / kebab / camel identifier into a human-readable label:
+ * tokenize (lowercased, capitalized), then join with spaces. Falls back to
+ * the raw `value` when it yields no tokens (e.g. punctuation-only input).
+ * `bge_large_en` -> `"Bge Large En"`, `promptId` -> `"Prompt Id"`.
+ *
+ * The single source of truth for the "humanize a column / field name" idiom -
+ * reused by the chat data-grid headers and the export renderer. Extra
+ * {@link TokenizeOptions} (e.g. `camelCase: false`) merge over the defaults.
+ */
+export declare function toLabel(value: string, options?: TokenizeOptions): string;
+/**
+ * Upper-case the first character of `value`, leaving the rest untouched.
+ * `"working"` -> `"Working"`. Collapses the
+ * `s.charAt(0).toUpperCase() + s.slice(1)` idiom.
+ */
+export declare function capitalize(value: string): string;