@fuzdev/fuz_util 0.42.0

package/dist/deep_equal.js

@@ -0,0 +1,152 @@
+/**
+ * Deep equality comparison that checks both structure and type.
+ *
+ * Key behaviors:
+ *
+ * - Compares by constructor to prevent type confusion (security: `{}` ≠ `[]`, `{}` ≠ `new Map()`, `new ClassA()` ≠ `new ClassB()`)
+ * - Prevents asymmetry bugs: `deep_equal(a, b)` always equals `deep_equal(b, a)`
+ * - Compares only enumerable own properties (ignores prototypes, symbols, non-enumerable)
+ * - Special handling for: Date (timestamp), Number/Boolean (boxed primitives), Error (message/name)
+ * - Promises always return false (cannot be meaningfully compared)
+ * - Maps/Sets compare by reference for object keys/values
+ *
+ * @param a first value to compare
+ * @param b second value to compare
+ * @returns true if deeply equal, false otherwise
+ */
+export const deep_equal = (a, b) => {
+    if (Object.is(a, b))
+        return true;
+    const a_type = typeof a;
+    if (a_type !== typeof b)
+        return false;
+    switch (a_type) {
+        case 'string':
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+        case 'symbol':
+        case 'undefined':
+        case 'function':
+            return false;
+        default:
+            break;
+    }
+    // a_type === 'object'
+    if (a === null || b === null)
+        return false;
+    // Constructor equality check prevents type confusion and ensures symmetry
+    // This means: {} ≠ [], {} ≠ new Map(), new ClassA() ≠ new ClassB()
+    // Security: prevents structural type confusion in equality checks
+    // Cache constructor for reuse in subsequent checks (avoids repeated property access)
+    const a_ctor = a.constructor;
+    if (a_ctor !== b.constructor)
+        return false;
+    // Regular arrays: inline length check before function call (fast-fail for mismatched lengths)
+    // Use Array.isArray() instead of instanceof Array (JIT-optimized, works cross-realm)
+    if (Array.isArray(a)) {
+        const len = a.length;
+        if (b.length !== len)
+            return false;
+        for (let i = 0; i < len; i++) {
+            if (!deep_equal(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    // Use cached constructor for type checks (faster than instanceof - avoids prototype chain walk)
+    if (a_ctor === Set) {
+        if (a.size !== b.size)
+            return false;
+        for (const a_value of a) {
+            if (!b.has(a_value))
+                return false;
+        }
+        return true;
+    }
+    if (a_ctor === Map) {
+        if (a.size !== b.size)
+            return false;
+        for (const [key, a_value] of a) {
+            if (!b.has(key) ||
+                !deep_equal(a_value, b.get(key)))
+                return false;
+        }
+        return true;
+    }
+    if (a_ctor === RegExp) {
+        return (a.source === b.source && a.flags === b.flags);
+    }
+    // Date objects: compare by timestamp value
+    if (a_ctor === Date) {
+        // Using Object.is to handle NaN correctly (invalid dates)
+        return Object.is(a.getTime(), b.getTime());
+    }
+    // ArrayBuffer: convert to Uint8Array views for byte-by-byte comparison
+    if (a_ctor === ArrayBuffer) {
+        if (a.byteLength !== b.byteLength)
+            return false;
+        const a_view = new Uint8Array(a);
+        const b_view = new Uint8Array(b);
+        const len = a.byteLength;
+        for (let i = 0; i < len; i++) {
+            if (a_view[i] !== b_view[i])
+                return false;
+        }
+        return true;
+    }
+    // TypedArrays: specialized fast path (no recursion needed - elements are always primitives)
+    // ArrayBuffer.isView() catches TypedArrays (Uint8Array, Int32Array, Float64Array, etc.)
+    // DataView is also caught by isView but needs special handling (no indexed access)
+    if (ArrayBuffer.isView(a)) {
+        // DataView: compare byte-by-byte using getUint8
+        if (a_ctor === DataView) {
+            const byte_len = a.byteLength;
+            if (b.byteLength !== byte_len)
+                return false;
+            for (let i = 0; i < byte_len; i++) {
+                if (a.getUint8(i) !== b.getUint8(i))
+                    return false;
+            }
+            return true;
+        }
+        // TypedArrays: use indexed access (much faster)
+        if (b.length !== a.length)
+            return false;
+        const len = a.length;
+        for (let i = 0; i < len; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+    // Boxed Number objects: compare by primitive value
+    if (a_ctor === Number) {
+        return Object.is(a.valueOf(), b.valueOf());
+    }
+    // Boxed Boolean objects: compare by primitive value
+    if (a_ctor === Boolean) {
+        return a.valueOf() === b.valueOf();
+    }
+    // Error objects: compare by message and name
+    if (a_ctor === Error) {
+        return a.message === b.message && a.name === b.name;
+    }
+    // Promise objects: cannot be meaningfully compared for deep equality
+    if (a_ctor === Promise) {
+        return false;
+    }
+    // Plain objects: compare enumerable own properties
+    const a_keys = Object.keys(a);
+    const a_keys_length = a_keys.length;
+    if (a_keys_length !== Object.keys(b).length)
+        return false;
+    for (let i = 0; i < a_keys_length; i++) {
+        const key = a_keys[i];
+        if (!(key in b))
+            return false;
+        if (!deep_equal(a[key], b[key]))
+            return false;
+    }
+    return true;
+};

package/dist/dom.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Checks if the given element is editable.
+ * Returns `true` for text-based input types, textareas, and contenteditable elements.
+ */
+export declare const is_editable: (el: any) => boolean;
+/**
+ * Returns `true` if the element is within a `contenteditable` ancestor.
+ */
+export declare const inside_editable: (el: Element) => boolean;
+/**
+ * Checks if the element is interactive (clickable, focusable, or otherwise accepts user input).
+ * Returns `true` for buttons, links, form controls,
+ * and elements with interactive attributes and ARIA roles.
+ */
+export declare const is_interactive: (el: any) => boolean;
+/**
+ * Stops an event from bubbling and doing default behavior.
+ * @param event
+ * @param immediate defaults to `true` to use `stopImmediatePropagation` over `stopPropagation`
+ * @param preventDefault defaults to `true`
+ * @mutates event calls preventDefault(), stopPropagation(), or stopImmediatePropagation()
+ * @returns
+ */
+export declare const swallow: <T extends Pick<Event, "preventDefault" | "stopPropagation" | "stopImmediatePropagation">>(event: T, immediate?: boolean, preventDefault?: boolean) => T;
+/**
+ * Handles the value of an event's target and invokes a callback.
+ * Defaults to swallowing the event to prevent default actions and propagation.
+ * @mutates event calls `swallow()` which mutates the event if `swallow_event` is true
+ */
+export declare const handle_target_value: (cb: (value: any, event: any) => void, swallow_event?: boolean) => (e: any) => void;
+/**
+ * Returns a boolean indicating if the current browser window, if any, is iframed inside of another.
+ */
+export declare const is_iframed: () => boolean;
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/dom.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,GAAG,KAAG,OASrC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,OAAO,KAAG,OAG7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,GAAG,KAAG,OA8BxC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GACnB,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,0BAA0B,CAAC,EAExF,OAAO,CAAC,EACR,mBAAgB,EAChB,wBAAqB,KACnB,CAQF,CAAC;AAGF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,EAAE,uBAAoB,MAC1D,GAAG,GAAG,KAAG,IAGT,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU,QAAO,OAO7B,CAAC"}

package/dist/dom.js

@@ -0,0 +1,95 @@
+/**
+ * Checks if the given element is editable.
+ * Returns `true` for text-based input types, textareas, and contenteditable elements.
+ */
+export const is_editable = (el) => {
+    if (!el)
+        return false;
+    const { tagName } = el;
+    return ((tagName === 'INPUT' && el.type !== 'hidden') ||
+        tagName === 'TEXTAREA' ||
+        el.contentEditable === 'true' ||
+        el.contentEditable === '' // Some browsers treat empty string as `'true'`
+    );
+};
+/**
+ * Returns `true` if the element is within a `contenteditable` ancestor.
+ */
+export const inside_editable = (el) => {
+    const found = el.closest('[contenteditable]');
+    return found !== null && found.contentEditable !== 'false';
+};
+/**
+ * Checks if the element is interactive (clickable, focusable, or otherwise accepts user input).
+ * Returns `true` for buttons, links, form controls,
+ * and elements with interactive attributes and ARIA roles.
+ */
+export const is_interactive = (el) => {
+    if (!el)
+        return false;
+    const { tagName } = el;
+    if (tagName === 'BUTTON' ||
+        tagName === 'SELECT' ||
+        tagName === 'TEXTAREA' ||
+        tagName === 'A' ||
+        tagName === 'AUDIO' ||
+        tagName === 'VIDEO' ||
+        (tagName === 'INPUT' && el.type !== 'hidden')) {
+        return true;
+    }
+    const role = el.getAttribute?.('role');
+    return ((role &&
+        (role === 'button' ||
+            role === 'link' ||
+            role === 'menuitem' ||
+            role === 'option' ||
+            role === 'switch' ||
+            role === 'tab')) ||
+        (el.hasAttribute?.('tabindex') && el.getAttribute('tabindex') !== '-1') ||
+        el.contentEditable === 'true' ||
+        el.contentEditable === '' ||
+        el.getAttribute?.('draggable') === 'true');
+};
+/**
+ * Stops an event from bubbling and doing default behavior.
+ * @param event
+ * @param immediate defaults to `true` to use `stopImmediatePropagation` over `stopPropagation`
+ * @param preventDefault defaults to `true`
+ * @mutates event calls preventDefault(), stopPropagation(), or stopImmediatePropagation()
+ * @returns
+ */
+export const swallow = (event, immediate = true, preventDefault = true) => {
+    if (preventDefault)
+        event.preventDefault();
+    if (immediate) {
+        event.stopImmediatePropagation();
+    }
+    else {
+        event.stopPropagation();
+    }
+    return event;
+};
+// TODO improve these types, the motivation was the strictness of Svelte DOM types
+/**
+ * Handles the value of an event's target and invokes a callback.
+ * Defaults to swallowing the event to prevent default actions and propagation.
+ * @mutates event calls `swallow()` which mutates the event if `swallow_event` is true
+ */
+export const handle_target_value = (cb, swallow_event = true) => (e) => {
+    if (swallow_event)
+        swallow(e);
+    cb(e.target.value, e);
+};
+/**
+ * Returns a boolean indicating if the current browser window, if any, is iframed inside of another.
+ */
+export const is_iframed = () => {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        return window.self !== window.top; // some browsers may throw here due to the same origin policy
+    }
+    catch (_err) {
+        return false;
+    }
+};

package/dist/error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Error for asserting unreachable code paths in TypeScript.
+ * Useful for exhaustive matching.
+ */
+export declare class UnreachableError extends Error {
+    constructor(value: never, message?: string, options?: ErrorOptions);
+}
+/**
+ * Beyond terseness, this is useful because `throw` is not an expression,
+ * and therefore can't be used in places like Svelte markup without a workaround,
+ * at least until this proposal is accepted and widely available:
+ * https://github.com/tc39/proposal-throw-expressions
+ */
+export declare const unreachable: (value: never, message?: string) => asserts value is never;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,KAAK,EAAE,KAAK,EAAE,OAAO,SAA+B,EAAE,OAAO,CAAC,EAAE,YAAY;CAGxF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,IAAI,KAK9E,CAAC"}

package/dist/error.js

@@ -0,0 +1,18 @@
+/**
+ * Error for asserting unreachable code paths in TypeScript.
+ * Useful for exhaustive matching.
+ */
+export class UnreachableError extends Error {
+    constructor(value, message = `Unreachable case: ${value}`, options) {
+        super(message, options);
+    }
+}
+/**
+ * Beyond terseness, this is useful because `throw` is not an expression,
+ * and therefore can't be used in places like Svelte markup without a workaround,
+ * at least until this proposal is accepted and widely available:
+ * https://github.com/tc39/proposal-throw-expressions
+ */
+export const unreachable = (value, message) => {
+    throw new UnreachableError(value, message);
+};

package/dist/fetch.d.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import type { Flavored } from './types.js';
+import type { Logger } from './log.js';
+import type { Result } from './result.js';
+export interface FetchValueOptions<TValue, TParams = undefined> {
+    /**
+     * The `request.headers` take precedence over the headers computed from other options.
+     */
+    request?: RequestInit;
+    params?: TParams;
+    parse?: (v: any) => TValue;
+    token?: string | null;
+    cache?: FetchValueCache | null;
+    return_early_from_cache?: boolean;
+    log?: Logger;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Specializes `fetch` with some slightly different behavior and additional features:
+ *
+ * - throws on ratelimit errors to mitigate unintentional abuse
+ * - optional `parse` function called on the return value
+ * - optional cache (different from the browser cache,
+ * 	 the caller can serialize it so e.g. dev setups can avoid hitting the network)
+ * - optional simplified API for authorization and data types
+ *   (you can still provide headers directly)
+ *
+ * Unlike `fetch`, this throws on ratelimits (status code 429)
+ * to halt whatever is happpening in its tracks to avoid accidental abuse,
+ * but returns a `Result` in all other cases.
+ * Handling ratelimit headers with more sophistication gets tricky because behavior
+ * differs across services.
+ * (e.g. Mastodon returns an ISO string for `x-ratelimit-reset`,
+ * but GitHub returns `Date.now()/1000`,
+ * and other services may do whatever, or even use a different header)
+ *
+ * It's also stateless to avoid the complexity and bugs,
+ * so we don't try to track `x-ratelimit-remaining` per domain.
+ *
+ * If the `value` is cached, only the cached safe subset of the `headers` are returned.
+ * (currently just `etag` and `last-modified`)
+ * Otherwise the full `res.headers` are included.
+ * @mutates options.cache calls `cache.set()` to store fetched results if cache is provided
+ */
+export declare const fetch_value: <TValue = any, TParams = undefined>(url: string | URL, options?: FetchValueOptions<TValue, TParams>) => Promise<Result<{
+    value: TValue;
+    headers: Headers;
+}, {
+    status: number;
+    message: string;
+}>>;
+export declare const FetchValueCacheKey: z.ZodString;
+export type FetchValueCacheKey = Flavored<z.infer<typeof FetchValueCacheKey>, 'FetchValueCacheKey'>;
+export declare const FetchValueCacheItem: z.ZodObject<{
+    key: z.ZodString;
+    url: z.ZodString;
+    params: z.ZodAny;
+    value: z.ZodAny;
+    etag: z.ZodNullable<z.ZodString>;
+    last_modified: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type FetchValueCacheItem = z.infer<typeof FetchValueCacheItem>;
+export declare const FetchValueCache: z.ZodMap<z.ZodString, z.ZodObject<{
+    key: z.ZodString;
+    url: z.ZodString;
+    params: z.ZodAny;
+    value: z.ZodAny;
+    etag: z.ZodNullable<z.ZodString>;
+    last_modified: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>;
+export type FetchValueCache = z.infer<typeof FetchValueCache>;
+export declare const to_fetch_value_cache_key: (url: string, params: any, method: string) => FetchValueCacheKey;
+/**
+ * Converts `FetchValueCache` to a JSON string.
+ */
+export declare const serialize_cache: (cache: FetchValueCache) => string;
+/**
+ * Converts a serialized cache string to a `FetchValueCache`.
+ */
+export declare const deserialize_cache: (serialized: string) => FetchValueCache;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAErC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAMxC,MAAM,WAAW,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS;IAC7D;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,WAAW,GAAU,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,SAAS,EAClE,KAAK,MAAM,GAAG,GAAG,EACjB,UAAU,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1C,OAAO,CAAC,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,EAAE;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CA2GtF,CAAC;AA4BF,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,EAAE,oBAAoB,CAAC,CAAC;AAEpG,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;kBAAiD,CAAC;AAC9E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAI9D,eAAO,MAAM,wBAAwB,GACpC,KAAK,MAAM,EACX,QAAQ,GAAG,EACX,QAAQ,MAAM,KACZ,kBAMF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,eAAe,KAAG,MACb,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,YAAY,MAAM,KAAG,eACA,CAAC"}

package/dist/fetch.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { EMPTY_OBJECT } from './object.js';
+import { json_stringify_deterministic } from './json.js';
+const DEFAULT_GITHUB_API_ACCEPT_HEADER = 'application/vnd.github+json';
+const DEFAULT_GITHUB_API_VERSION_HEADER = '2022-11-28';
+/**
+ * Specializes `fetch` with some slightly different behavior and additional features:
+ *
+ * - throws on ratelimit errors to mitigate unintentional abuse
+ * - optional `parse` function called on the return value
+ * - optional cache (different from the browser cache,
+ * 	 the caller can serialize it so e.g. dev setups can avoid hitting the network)
+ * - optional simplified API for authorization and data types
+ *   (you can still provide headers directly)
+ *
+ * Unlike `fetch`, this throws on ratelimits (status code 429)
+ * to halt whatever is happpening in its tracks to avoid accidental abuse,
+ * but returns a `Result` in all other cases.
+ * Handling ratelimit headers with more sophistication gets tricky because behavior
+ * differs across services.
+ * (e.g. Mastodon returns an ISO string for `x-ratelimit-reset`,
+ * but GitHub returns `Date.now()/1000`,
+ * and other services may do whatever, or even use a different header)
+ *
+ * It's also stateless to avoid the complexity and bugs,
+ * so we don't try to track `x-ratelimit-remaining` per domain.
+ *
+ * If the `value` is cached, only the cached safe subset of the `headers` are returned.
+ * (currently just `etag` and `last-modified`)
+ * Otherwise the full `res.headers` are included.
+ * @mutates options.cache calls `cache.set()` to store fetched results if cache is provided
+ */
+export const fetch_value = async (url, options) => {
+    const { request, params, parse, token, cache, return_early_from_cache, log, fetch = globalThis.fetch, } = options ?? EMPTY_OBJECT;
+    const url_obj = typeof url === 'string' ? new URL(url) : url;
+    const url_str = url_obj.href;
+    const method = request?.method ?? (params ? 'POST' : 'GET');
+    // local cache?
+    let cached;
+    let key;
+    if (cache) {
+        key = to_fetch_value_cache_key(url_str, params, method);
+        cached = cache.get(key);
+        if (return_early_from_cache && cached) {
+            log?.info('[fetch_value] cached locally and returning early', url_str);
+            log?.debug('[fetch_value] cached value', cached);
+            return { ok: true, value: cached.value, headers: to_cached_headers(cached) };
+        }
+    }
+    const body = request?.body ?? (method === 'GET' || method === 'HEAD' ? null : JSON.stringify(params ?? {}));
+    const headers = new Headers(request?.headers);
+    if (!headers.has('accept')) {
+        headers.set('accept', url_obj.hostname === 'api.github.com' ? DEFAULT_GITHUB_API_ACCEPT_HEADER : 'application/json');
+    }
+    if (headers.get('accept') === DEFAULT_GITHUB_API_ACCEPT_HEADER &&
+        !headers.has('x-github-api-version')) {
+        headers.set('x-github-api-version', DEFAULT_GITHUB_API_VERSION_HEADER);
+    }
+    if (body && !headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    if (token && !headers.has('authorization')) {
+        headers.set('authorization', 'Bearer ' + token);
+    }
+    const etag = cached?.etag;
+    if (etag && !headers.has('if-none-match')) {
+        headers.set('if-none-match', etag);
+    }
+    else {
+        // fall back to last-modified, ignoring if there's an etag
+        const last_modified = cached?.last_modified;
+        if (last_modified && !headers.has('if-modified-since')) {
+            headers.set('if-modified-since', last_modified);
+        }
+    }
+    const req = new Request(url_obj, { ...request, headers, method, body });
+    log?.info('[fetch_value] fetching url with headers', url);
+    log?.debug('[fetch_value] fetching with headers', print_headers(headers));
+    const res = await fetch(req); // don't catch network errors
+    log?.info('[fetch_value] fetched', url, res.status, print_ratelimit_headers(res.headers));
+    log?.debug('[fetch_value] fetched', Object.fromEntries(res.headers.entries()));
+    // throw on ratelimit
+    if (res.status === 429) {
+        throw Error('ratelimited exceeded fetching url ' + url);
+    }
+    // return from cache if it hits
+    if (res.status === 304) {
+        if (!cached)
+            throw Error('unexpected 304 status without a cached value');
+        log?.info('[fetch_value] cache hit', url);
+        return { ok: true, value: cached.value, headers: to_cached_headers(cached) };
+    }
+    if (!res.ok) {
+        return { ok: false, status: res.status, message: res.statusText };
+    }
+    const content_type = res.headers.get('content-type');
+    const fetched = await (!content_type || content_type.includes('json') ? res.json() : res.text()); // TODO hacky
+    const parsed = parse ? parse(fetched) : fetched;
+    log?.debug('[fetch_value] fetched json', url, parsed);
+    if (key) {
+        const result = {
+            key,
+            url: url_str,
+            params,
+            value: parsed,
+            etag: res.headers.get('etag'),
+            last_modified: res.headers.get('etag') ? null : res.headers.get('last-modified'), // fall back to last-modified, ignoring if there's an etag
+        };
+        cache.set(key, result);
+    }
+    return { ok: true, value: parsed, headers: res.headers };
+};
+/**
+ * Returns a subset of headers that are safe to store in a `fetch_value` cache.
+ */
+const to_cached_headers = (cached) => {
+    const headers = new Headers();
+    if (cached.etag) {
+        headers.set('etag', cached.etag);
+    }
+    if (cached.last_modified) {
+        headers.set('last-modified', cached.last_modified);
+    }
+    return headers;
+};
+const print_headers = (headers) => {
+    const h = Object.fromEntries(headers.entries());
+    if (h.authorization)
+        h.authorization = '[REDACTED]';
+    return h;
+};
+const print_ratelimit_headers = (headers) => {
+    const limit = headers.get('x-ratelimit-limit');
+    const remaining = headers.get('x-ratelimit-remaining');
+    return limit || remaining ? `ratelimit ${remaining} of ${limit}` : '';
+};
+export const FetchValueCacheKey = z.string();
+export const FetchValueCacheItem = z.object({
+    key: FetchValueCacheKey,
+    url: z.string(),
+    params: z.any(),
+    value: z.any(),
+    etag: z.string().nullable(),
+    last_modified: z.string().nullable(),
+});
+export const FetchValueCache = z.map(FetchValueCacheKey, FetchValueCacheItem);
+const KEY_SEPARATOR = '::';
+export const to_fetch_value_cache_key = (url, params, method) => {
+    let key = method + KEY_SEPARATOR + url;
+    if (params != null) {
+        key += KEY_SEPARATOR + json_stringify_deterministic(params);
+    }
+    return key;
+};
+/**
+ * Converts `FetchValueCache` to a JSON string.
+ */
+export const serialize_cache = (cache) => JSON.stringify(Array.from(cache.entries()));
+/**
+ * Converts a serialized cache string to a `FetchValueCache`.
+ */
+export const deserialize_cache = (serialized) => FetchValueCache.parse(new Map(JSON.parse(serialized)));

package/dist/fs.d.ts

@@ -0,0 +1,34 @@
+import type { RmOptions } from 'node:fs';
+import type { FileFilter, ResolvedPath, PathFilter } from './path.js';
+/**
+ * Checks if a file or directory exists.
+ */
+export declare const fs_exists: (path: string) => Promise<boolean>;
+/**
+ * Empties a directory, recursively by default. If `should_remove` is provided, only entries where it returns `true` are removed.
+ */
+export declare const fs_empty_dir: (dir: string, should_remove?: (name: string) => boolean, options?: RmOptions) => Promise<void>;
+export interface FsSearchOptions {
+    /**
+     * One or more filter functions, any of which can short-circuit the search by returning `false`.
+     */
+    filter?: PathFilter | Array<PathFilter>;
+    /**
+     * One or more file filter functions. Every filter must pass for a file to be included.
+     */
+    file_filter?: FileFilter | Array<FileFilter>;
+    /**
+     * Pass `null` or `false` to speed things up at the cost of volatile ordering.
+     */
+    sort?: boolean | null | ((a: ResolvedPath, b: ResolvedPath) => number);
+    /**
+     * Set to `true` to include directories. Defaults to `false`.
+     */
+    include_directories?: boolean;
+    /**
+     * Sets the cwd for `dir` unless it's an absolute path or `null`.
+     */
+    cwd?: string | null;
+}
+export declare const fs_search: (dir: string, options?: FsSearchOptions) => Promise<Array<ResolvedPath>>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/fs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAMvC,OAAO,KAAK,EAAC,UAAU,EAAE,YAAY,EAAE,UAAU,EAAC,MAAM,WAAW,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,SAAS,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,OAAO,CAO7D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GACxB,KAAK,MAAM,EACX,gBAAgB,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,EACzC,UAAU,SAAS,KACjB,OAAO,CAAC,IAAI,CAId,CAAC;AAEF,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IACxC;;OAEG;IACH,WAAW,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IAC7C;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,KAAK,MAAM,CAAC,CAAC;IACvE;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,eAAO,MAAM,SAAS,GACrB,KAAK,MAAM,EACX,UAAS,eAA8B,KACrC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CA2B7B,CAAC"}