@zajno/common 2.8.6 → 2.8.8

package/cjs/api/call.config.js

@@ -2,9 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RequestMeta = void 0;
 exports.createConfig = createConfig;
+const isPlainObject_js_1 = require("../types/isPlainObject.js");
 const config_js_1 = require("./config.js");
 function createConfig(endpointsConfig, api, data, extra) {
     const { headers, log = 'res', noLoader, ...restExtra } = extra || {};
+    // Guard against non-plain objects (e.g. FormData, Blob) that would be destroyed by spread.
+    // Only plain objects can be spread for path/query extraction.
+    if (data != null && typeof data === 'object' && !(0, isPlainObject_js_1.isPlainObject)(data)) {
+        const name = data.constructor?.name ?? typeof data;
+        throw new TypeError(`API caller received a non-plain object as data (got ${name}). `
+            + 'Only plain objects are supported because data is spread for path/query extraction. '
+            + 'For FormData/multipart uploads, pass a plain object and use the IEndpointFormData extension '
+            + 'with .asFormData(), or use a beforeRequest hook to replace config.data.');
+    }
     const resultInput = data && { ...data };
     const pathInputs = {};
     const queryInputs = {};

package/cjs/api/call.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"call.config.js","sourceRoot":"","sources":["../../../src/api/call.config.ts"],"names":[],"mappings":";;;AAMA,oCA4EC;AAhFD,2CAAmD;AAInD,SAAgB,YAAY,CACxB,eAAqC,EACrC,GAAM,EACN,IAAiC,EACjC,KAAgC;IAKhC,MAAM,EACF,OAAO,EACP,GAAG,GAAG,KAAK,EACX,QAAQ,EACR,GAAG,SAAS,EACf,GAAG,KAAK,IAAI,EAAE,CAAC;IAEhB,MAAM,WAAW,GAAG,IAAI,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;IACxC,MAAM,UAAU,GAAoC,EAAE,CAAC;IACvD,MAAM,WAAW,GAAc,EAAE,CAAC;IAClC,IAAI,QAAQ,GAAW,EAAE,CAAC;IAE1B,gCAAgC;IAChC,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC;IAChC,IAAI,WAAW,IAAI,QAAQ,EAAE,MAAM,EAAE,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YACzB,UAAU,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YACnC,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;IAED,iCAAiC;IACjC,MAAM,iBAAiB,GAAG,GAAG,CAAC,SAAS,CAAC;IACxC,IAAI,WAAW,IAAI,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC3C,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;YAClC,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;gBACZ,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACrB,KAAK,GAAG,KAAK,CAAC;YAClB,CAAC;YACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,uBAAuB;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC;YAChD,QAAQ,GAAG,GAAG,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QACvC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAG,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;QAClE,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;IACnC,MAAM,MAAM,GAAmC;QAC3C,MAAM;QACN,GAAG,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,UAA0C,CAAC,GAAG,QAAQ;QACxF,IAAI,EAAE,WAAW,IAAI,SAAS;QAC9B,OAAO,EAAE,OAAoB,IAAI,EAAE;QAEnC,KAAK,EAAE,IAAI,WAAW,CAClB,GAAG,EACH,eAAe,EACf,GAAG,EACH,QAAQ,IAAI,MAAgB,KAAK,KAAK,EACtC,SAAmB,CACtB;KACJ,CAAC;IAEF,OAAO;QACH,MAAM;QACN,WAAW;QACX,UAAU;QACV,WAAW;KACd,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAa,WAAW;IAEA;IACA;IACA;IACA;IACA;IALpB,YACoB,GAAM,EACN,cAAoC,IAAI,gCAAoB,EAAE,EAC9D,MAAgB,KAAK,EACrB,WAAoB,KAAK,EACzB,QAAgB,EAA8B;QAJ9C,QAAG,GAAH,GAAG,CAAG;QACN,gBAAW,GAAX,WAAW,CAAmD;QAC9D,QAAG,GAAH,GAAG,CAAkB;QACrB,aAAQ,GAAR,QAAQ,CAAiB;QACzB,UAAK,GAAL,KAAK,CAAyC;IAGlE,CAAC;CACJ;AAVD,kCAUC"}
+{"version":3,"file":"call.config.js","sourceRoot":"","sources":["../../../src/api/call.config.ts"],"names":[],"mappings":"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"}

package/cjs/api/extensions/formData.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IEndpointFormData = void 0;
+exports.createFormDataSerializer = createFormDataSerializer;
+const isPlainObject_js_1 = require("../../types/isPlainObject.js");
+/**
+ * Creates a default FormData serializer.
+ *
+ * Iterates over own enumerable properties of the data object and appends them to a new FormData instance.
+ *
+ * - `Blob`/`File` values are appended as-is
+ * - `null`/`undefined` values are skipped
+ * - Primitive values are converted to strings
+ * - Objects/arrays are JSON-stringified by default (configurable via `serializeValue`)
+ */
+function createFormDataSerializer(options) {
+    const Ctor = options?.FormData ?? globalThis.FormData;
+    if (typeof Ctor !== 'function') {
+        throw new TypeError('FormData is not available in this environment. '
+            + 'Pass a FormData constructor via options.FormData (e.g., from the `form-data` npm package).');
+    }
+    const serializeValue = options?.serializeValue ?? 'json';
+    return (data) => {
+        const fd = new Ctor();
+        for (const [key, value] of Object.entries(data)) {
+            if (value == null) {
+                continue;
+            }
+            if (typeof Blob !== 'undefined' && value instanceof Blob) {
+                fd.append(key, value);
+                continue;
+            }
+            if (typeof value !== 'object') {
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                fd.append(key, String(value));
+                continue;
+            }
+            if (typeof serializeValue === 'function') {
+                const serialized = serializeValue(key, value);
+                if (typeof Blob !== 'undefined' && serialized instanceof Blob) {
+                    fd.append(key, serialized);
+                }
+                else {
+                    fd.append(key, serialized);
+                }
+            }
+            else {
+                fd.append(key, JSON.stringify(value));
+            }
+        }
+        return fd;
+    };
+}
+var IEndpointFormData;
+(function (IEndpointFormData) {
+    IEndpointFormData.extender = (base) => {
+        const ext = {
+            formData: undefined,
+            asFormData(serializer) {
+                this.formData = serializer ?? true;
+                return this;
+            },
+        };
+        return Object.assign(base, ext);
+    };
+    function guard(api) {
+        return 'formData' in api && !!api.formData;
+    }
+    IEndpointFormData.guard = guard;
+    /**
+     * Creates caller hooks for FormData serialization.
+     *
+     * The hook converts `config.data` (plain object) into a FormData instance using the provided serializer.
+     *
+     * @param serializer - Default serializer used when endpoint has `.asFormData()` without a custom serializer.
+     *   Use {@link createFormDataSerializer} for the built-in one, or provide a fully custom function.
+     *
+     * @example
+     * ```typescript
+     * // Simplest setup (global FormData, JSON-stringify objects)
+     * IEndpointFormData.createHooks(createFormDataSerializer())
+     *
+     * // Custom FormData constructor
+     * import FormDataNode from 'form-data';
+     * IEndpointFormData.createHooks(createFormDataSerializer({ FormData: FormDataNode as any }))
+     *
+     * // Fully custom serializer
+     * IEndpointFormData.createHooks((data) => {
+     *     const fd = new FormData();
+     *     // custom logic...
+     *     return fd;
+     * })
+     * ```
+     */
+    function createHooks(serializer) {
+        return {
+            beforeRequest: (config) => {
+                if (!guard(config._meta.api) || !config.data) {
+                    return;
+                }
+                // Skip if data was already transformed by a previous hook (e.g., to FormData, Blob, string)
+                if (!(0, isPlainObject_js_1.isPlainObject)(config.data)) {
+                    return;
+                }
+                const endpoint = config._meta.api;
+                const ser = typeof endpoint.formData === 'function'
+                    ? endpoint.formData
+                    : serializer;
+                config.data = ser(config.data);
+            },
+        };
+    }
+    IEndpointFormData.createHooks = createHooks;
+})(IEndpointFormData || (exports.IEndpointFormData = IEndpointFormData = {}));
+//# sourceMappingURL=formData.js.map

package/cjs/api/extensions/formData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formData.js","sourceRoot":"","sources":["../../../../src/api/extensions/formData.ts"],"names":[],"mappings":"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"}

package/cjs/api/extensions/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./contentType.js"), exports);
+tslib_1.__exportStar(require("./formData.js"), exports);
 tslib_1.__exportStar(require("./validation.js"), exports);
 tslib_1.__exportStar(require("./endpointHooks.js"), exports);
 //# sourceMappingURL=index.js.map

package/cjs/api/extensions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/extensions/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC;AACjC,0DAAgC;AAChC,6DAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/extensions/index.ts"],"names":[],"mappings":";;;AAAA,2DAAiC;AACjC,wDAA8B;AAC9B,0DAAgC;AAChC,6DAAmC"}

package/cjs/structures/promiseCache/cache.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromiseCache = void 0;
+const debounce_js_1 = require("../../functions/debounce.js");
+const core_js_1 = require("./core.js");
+const BATCHING_DELAY = 200;
+/**
+ * Caches items by a key (string or another type) which are resolved by an async fetcher (`Promise`).
+ *
+ * Supports:
+ *  - custom key adapter and parser for non-string keys.
+ *  - direct manual cache manipulation.
+ *  - batching of fetches.
+ *  - auto-invalidation of cached items (time-based, callback-based, max items).
+ *  - error tracking per key.
+*/
+class PromiseCache extends core_js_1.PromiseCacheCore {
+    fetcher;
+    _batch = null;
+    _invalidationConfig = null;
+    _onError = null;
+    /**
+     * Creates an instance of PromiseCache.
+     * @param fetcher Function to fetch data by key.
+     * @param keyAdapter Optional function to adapt non-string keys to strings.
+     * @param keyParser Optional function to parse string keys back to their original type.
+     */
+    constructor(fetcher, keyAdapter, keyParser) {
+        super(keyAdapter, keyParser);
+        this.fetcher = fetcher;
+    }
+    // ─── Configuration ───────────────────────────────────────────────────
+    /**
+     * Provide a fetcher function that takes multiple ids and returns multiple results at once. Will be called with a slight delay to allow multiple ids to be collected.
+     *
+     * Warning: resolved array should have the same order as the input array.
+     *
+     * When provided, effectively replaces the main fetcher; but in case of fail, fallbacks to the main fetcher.
+    */
+    useBatching(fetcher, delay = BATCHING_DELAY) {
+        this._batch = fetcher ? new debounce_js_1.DebounceProcessor(fetcher, delay) : null;
+        return this;
+    }
+    /**
+     * Enables auto-invalidation of cached items by time.
+     *
+     * This is a convenience wrapper around {@link useInvalidation}.
+     *
+     * @param ms Time in milliseconds after which the item will be considered invalid. If null, auto-invalidation is disabled.
+     * @param keepInstance If true, the cached item will not be removed during invalidation, but the old instance is kept. Defaults to false.
+    */
+    useInvalidationTime(ms, keepInstance = false) {
+        return this.useInvalidation(ms != null ? { expirationMs: ms, keepInstance } : null);
+    }
+    /**
+     * Configures advanced invalidation policy.
+     *
+     * The config object is stored as-is (not destructured), so getter-based fields will be re-evaluated on each access.
+     * This allows consumers to provide dynamic invalidation policies.
+     *
+     * @param config The invalidation configuration. See {@link InvalidationConfig} for details.
+     */
+    useInvalidation(config) {
+        this._invalidationConfig = config;
+        return this;
+    }
+    /**
+     * Sets an error callback that is called when a fetcher fails.
+     *
+     * @param callback The callback to call on error. Receives the original key and the raw error.
+     */
+    useOnError(callback) {
+        this._onError = callback;
+        return this;
+    }
+    // ─── Core implementation ─────────────────────────────────────────────
+    /**
+     * Returns a promise that resolves to the cached value of the item if loaded already, otherwise starts fetching and the promise will be resolved to the final value.
+     *
+     * Consequent calls will return the same promise until it resolves.
+     *
+     * @param id The id of the item.
+     * @returns A promise that resolves to the result, whether it's cached or freshly fetched.
+     */
+    get(id) {
+        const { item, key, isInvalid } = this._getCurrent(id);
+        // return cached item if it's not invalidated
+        if (item !== undefined && !isInvalid) {
+            this.logger.log(key, 'get: item resolved to', item, isInvalid ? '(invalidated)' : '');
+            return Promise.resolve(item);
+        }
+        let promise = this._fetchCache.get(key);
+        if (promise != null) {
+            this.logger.log(key, 'get: item resolved to <promise>');
+            return promise;
+        }
+        this.setStatus(key, true);
+        promise = this._doFetchAsync(id, key);
+        this.setPromise(key, promise);
+        return promise;
+    }
+    /** Clears the cache and resets the loading state. */
+    clear() {
+        this._batch?.clear();
+        super.clear();
+    }
+    // ─── Protected overrides ─────────────────────────────────────────────
+    _getCurrent(id) {
+        const key = this._pk(id);
+        const isInvalid = this.getIsInvalidated(key);
+        // make sure current item is hooked here from the cache (required by observers)
+        const item = this._itemsCache.get(key);
+        const keepInstance = !!this._invalidationConfig?.keepInstance;
+        if (isInvalid) {
+            this.logger.log(key, 'item is invalidated');
+        }
+        return {
+            item: (isInvalid && !keepInstance) ? undefined : item,
+            key,
+            isInvalid,
+        };
+    }
+    getIsInvalidated(key) {
+        const config = this._invalidationConfig;
+        if (!config) {
+            return false;
+        }
+        const ts = this._timestamps.get(key);
+        // Check time-based expiration
+        const expirationMs = config.expirationMs;
+        if (expirationMs != null && expirationMs > 0 && ts != null) {
+            if (Date.now() - ts > expirationMs) {
+                return true;
+            }
+        }
+        // Check callback-based invalidation
+        if (config.invalidationCheck) {
+            const value = this._itemsCache.get(key);
+            if (value !== undefined && config.invalidationCheck(key, value, ts ?? 0)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** @override Stores the result for the specified key, enforcing max items. */
+    storeResult(key, res) {
+        this._enforceMaxItems(key);
+        super.storeResult(key, res);
+    }
+    // ─── Private ─────────────────────────────────────────────────────────
+    /**
+     * Fetches the item asynchronously.
+     * @param id The id of the item.
+     * @param key The cache key.
+     * @returns A promise that resolves to the fetched item.
+     */
+    async _doFetchAsync(id, key) {
+        let isInSameVersion = true;
+        try {
+            this.onBeforeFetch(key);
+            const v = this._version;
+            let res;
+            let fetchFailed = false;
+            try {
+                res = await this.tryFetchInBatch(id);
+            }
+            catch (err) {
+                this._handleError(id, err);
+                fetchFailed = true;
+                res = null;
+            }
+            if (v !== this._version) {
+                isInSameVersion = false;
+                // resolve with actual result but don't store it
+                return res;
+            }
+            if (this._fetchCache.get(key) != null) {
+                this.logger.log(key, 'item\'s <promise> resolved to', res);
+                res = this.prepareResult(res);
+                if (!fetchFailed) {
+                    this.storeResult(key, res);
+                }
+            }
+            return res;
+        }
+        finally {
+            if (isInSameVersion) {
+                this.onFetchComplete(key);
+            }
+            else {
+                this.logger.log(key, 'skipping item\'s resolve due to version change ("clear()" has been called)');
+            }
+        }
+    }
+    /** Performs a fetch operation in batch mode if available, otherwise uses the regular fetch. Throws on error. */
+    async tryFetchInBatch(id) {
+        if (!this._batch) {
+            return this.fetcher(id);
+        }
+        const res = await this._batch.push(id)
+            .catch(err => {
+            this.logger.warn('batch fetch failed', id, err);
+            return null;
+        });
+        if (!res || !res.result || res.result[res.index] === undefined) {
+            // batch call failed or returned no result — fallback to the direct fetcher
+            return this.fetcher(id);
+        }
+        return res.result[res.index];
+    }
+    /** Handles a fetch error: stores it, logs it, and calls the onError callback. */
+    _handleError(id, err) {
+        const key = this._pk(id);
+        this._errorsMap.set(key, err);
+        this.logger.warn('fetcher failed', id, err);
+        if (this._onError) {
+            try {
+                this._onError(id, err);
+            }
+            catch {
+                // ignore errors in the callback
+            }
+        }
+    }
+    /**
+     * Enforces the max items limit by removing items to make room.
+     * Strategy: first removes invalid items, then oldest valid items.
+     * Items currently being fetched (in-flight) are not evicted.
+     *
+     * @param incomingKey The key of the item about to be stored (excluded from eviction).
+     */
+    _enforceMaxItems(incomingKey) {
+        const maxItems = this._invalidationConfig?.maxItems;
+        if (maxItems == null || maxItems <= 0) {
+            return;
+        }
+        // If we're under the limit, nothing to do
+        if (this._itemsCache.size < maxItems) {
+            return;
+        }
+        // Phase 1: Remove invalid items first (they're garbage anyway)
+        const invalidKeys = [];
+        for (const key of this._itemsCache.keys()) {
+            if (key === incomingKey)
+                continue;
+            if (this.getIsInvalidated(key)) {
+                invalidKeys.push(key);
+            }
+        }
+        for (const key of invalidKeys) {
+            this._set(key, undefined, undefined, undefined);
+            this._errorsMap.delete(key);
+            this._timestamps.delete(key);
+            if (this._itemsCache.size < maxItems) {
+                return;
+            }
+        }
+        // Phase 2: Remove oldest valid items (skip in-flight items)
+        while (this._itemsCache.size >= maxItems) {
+            let oldestKey = null;
+            let oldestTs = Infinity;
+            for (const [key, ts] of this._timestamps.entries()) {
+                // Don't evict the incoming key or items currently being fetched
+                if (key === incomingKey)
+                    continue;
+                if (this._fetchCache.has(key))
+                    continue;
+                if (ts < oldestTs) {
+                    oldestTs = ts;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey != null) {
+                this._set(oldestKey, undefined, undefined, undefined);
+                this._timestamps.delete(oldestKey);
+                this._errorsMap.delete(oldestKey);
+            }
+            else {
+                // No evictable items found (all are in-flight or incoming)
+                break;
+            }
+        }
+    }
+}
+exports.PromiseCache = PromiseCache;
+//# sourceMappingURL=cache.js.map

package/cjs/structures/promiseCache/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/cache.ts"],"names":[],"mappings":"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"}