@nitrostack/core 1.0.17 → 1.1.0-beta.0

package/dist/core/interceptors/data-spillover.interceptor.js

@@ -0,0 +1,174 @@
+import { v4 as uuidv4 } from 'uuid';
+import { DIContainer } from '../di/container.js';
+import { MemorySpilloverStore } from './spillover/memory-spillover.store.js';
+import { FsSpilloverStore } from './spillover/fs-spillover.store.js';
+import { generatePreview } from './spillover/preview-generator.js';
+class PayloadTooLargeError extends Error {
+    constructor(sizeBytes, maxBytes) {
+        super(`Spillover payload of ${sizeBytes} bytes exceeds the store limit of ${maxBytes} bytes. ` +
+            `Raise the store maxSizeBytes or use a larger spillover driver.`);
+        this.name = 'PayloadTooLargeError';
+    }
+}
+/** JSON.stringify that aborts once the output would exceed maxBytes. */
+function stringifyCapped(value, maxBytes) {
+    let accounted = 0;
+    const json = JSON.stringify(value, (_key, val) => {
+        if (typeof val === 'string')
+            accounted += val.length;
+        else if (typeof val === 'number' || typeof val === 'boolean' || val === null)
+            accounted += 16;
+        if (accounted > maxBytes) {
+            throw new PayloadTooLargeError(accounted, maxBytes);
+        }
+        return val;
+    });
+    if (json == null)
+        return 'null';
+    const size = Buffer.byteLength(json, 'utf8');
+    if (size > maxBytes)
+        throw new PayloadTooLargeError(size, maxBytes);
+    return json;
+}
+export class DataSpilloverInterceptor {
+    maxPayloadBytes;
+    spilloverTtlSeconds;
+    previewItems;
+    previewChars;
+    uriPrefix;
+    explicitStore;
+    filesystemRequested;
+    fallbackStore;
+    constructor(options = {}) {
+        this.maxPayloadBytes = options.maxPayloadBytes ?? 10 * 1024; // 10KB
+        this.spilloverTtlSeconds = options.spilloverTtlSeconds ?? 3600; // 1 hr
+        this.previewItems = options.previewItems ?? 3;
+        this.previewChars = options.previewStringChars ?? 500;
+        this.uriPrefix = options.resourceUriPrefix ?? 'resource://data-spillover/';
+        this.filesystemRequested = options.storage === 'filesystem';
+        if (options.storage && typeof options.storage === 'object') {
+            this.explicitStore = options.storage;
+        }
+    }
+    /**
+     * Static factory helper for @UseInterceptors decorator:
+     */
+    static configure(options) {
+        return class ConfiguredDataSpilloverInterceptor extends DataSpilloverInterceptor {
+            constructor() {
+                super(options);
+            }
+        };
+    }
+    /**
+     * The store this interceptor writes to.
+     *
+     * Defaults to the server's store rather than a private one: the envelope's
+     * `resourceUri` is served by the server's `resource://data-spillover/{id}` handler,
+     * so writing anywhere else produces URIs that can never be read back.
+     */
+    serverHost() {
+        const container = DIContainer.getInstance();
+        if (!container.has('NitroStackServer'))
+            return undefined;
+        const server = container.resolve('NitroStackServer');
+        if (typeof server?.getSpilloverStore !== 'function')
+            return undefined;
+        return server;
+    }
+    getStore() {
+        const host = this.serverHost();
+        if (this.explicitStore) {
+            if (host && host.getSpilloverStore() !== this.explicitStore) {
+                throw new Error('DataSpilloverInterceptor storage instance is not the server spillover store. ' +
+                    'Omit storage to use the server store, or point the server at this instance with setSpilloverStore().');
+            }
+            return this.explicitStore;
+        }
+        if (this.filesystemRequested) {
+            const current = host?.getSpilloverStore();
+            if (current instanceof FsSpilloverStore)
+                return current;
+            throw new Error('DataSpilloverInterceptor requested filesystem storage, but the server spillover store is not a filesystem store. ' +
+                'Set the server spillover driver to filesystem.');
+        }
+        // Read through on every call rather than memoizing, so setSpilloverStore() on the
+        // server does not leave this interceptor writing to a disposed store.
+        if (host)
+            return host.getSpilloverStore();
+        this.fallbackStore ??= new MemorySpilloverStore();
+        return this.fallbackStore;
+    }
+    async intercept(context, next) {
+        const result = await next();
+        if (result === undefined || result === null) {
+            return result;
+        }
+        const store = this.getStore();
+        const quota = store.getMaxSizeBytes?.() ?? 100 * 1024 * 1024;
+        // Measure serialized size
+        let serialized;
+        let mimeType = 'application/json';
+        if (typeof result === 'string') {
+            serialized = result;
+            mimeType = 'text/plain';
+        }
+        else if (Buffer.isBuffer(result)) {
+            if (result.length > quota)
+                throw new PayloadTooLargeError(result.length, quota);
+            serialized = result.toString('base64');
+            mimeType = 'application/octet-stream';
+        }
+        else {
+            try {
+                serialized = stringifyCapped(result, quota);
+            }
+            catch (err) {
+                if (err instanceof PayloadTooLargeError)
+                    throw err;
+                // Not serializable; pass through
+                return result;
+            }
+        }
+        const sizeBytes = Buffer.byteLength(serialized, 'utf8');
+        // If within limit, pass through unmodified
+        if (sizeBytes <= this.maxPayloadBytes) {
+            return result;
+        }
+        if (sizeBytes > quota) {
+            throw new PayloadTooLargeError(sizeBytes, quota);
+        }
+        // Exceeded threshold: spillover to storage.
+        // With visibility installed, a row without a session would be readable by
+        // anyone who learned the URI, so refuse the write instead.
+        if (!context?.sessionId && this.serverHost()?.hasSessionVisibility?.()) {
+            throw new Error('Spillover requires a session when visibility is enabled. ' +
+                'Call this tool with a server-issued session id.');
+        }
+        const spilloverId = `spill-${uuidv4()}`;
+        const resourceUri = `${this.uriPrefix}${spilloverId}`;
+        await store.save(spilloverId, serialized, mimeType, this.spilloverTtlSeconds, context?.sessionId);
+        const { preview, summary, totalItems } = generatePreview(result, sizeBytes, this.previewItems, this.previewChars);
+        if (context?.logger?.info) {
+            context.logger.info(`Spilled tool output exceeding threshold (${sizeBytes} bytes) to ${resourceUri}`);
+        }
+        const envelope = {
+            _spillover: true,
+            resourceUri,
+            mimeType,
+            sizeBytes,
+            totalItems,
+            summary,
+            preview,
+            hint: `Full dataset (${summary}) exceeded prompt limit. Read full data via MCP resources/read with URI '${resourceUri}'.`,
+        };
+        // A nested value (for example `{ rows: [...] }`) can still exceed the limit
+        // after preview slicing. Drop that preview rather than re-inline the payload.
+        const previewBytes = Buffer.byteLength(JSON.stringify(envelope.preview) ?? '', 'utf8');
+        if (previewBytes > this.maxPayloadBytes) {
+            envelope.preview = '[preview omitted]';
+        }
+        return envelope;
+    }
+}
+//# sourceMappingURL=data-spillover.interceptor.js.map

package/dist/core/interceptors/data-spillover.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-spillover.interceptor.js","sourceRoot":"","sources":["../../../src/core/interceptors/data-spillover.interceptor.ts"],"names":[],"mappings":"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"}

package/dist/core/interceptors/interceptor.decorator.d.ts

@@ -1,5 +1,7 @@
 import 'reflect-metadata';
-import { InterceptorConstructor } from './interceptor.interface.js';
+import { InterceptorType } from './interceptor.interface.js';
+export declare const INTERCEPTOR_KEY = "nitrostack:interceptor";
+export declare const IS_INTERCEPTOR_KEY = "nitrostack:is_interceptor";
 /**
  * Marks a class as an interceptor
  *
@@ -16,20 +18,27 @@ import { InterceptorConstructor } from './interceptor.interface.js';
  */
 export declare function Interceptor(): ClassDecorator;
 /**
- * Apply interceptors to a tool method
+ * Apply interceptors to a tool method or to an entire controller class.
+ * Supports both class constructors and pre-configured instances.
  *
  * @example
  * ```typescript
- * @Tool({ name: 'get_user', ... })
- * @UseInterceptors(TransformInterceptor, CacheInterceptor)
- * async getUser(input: Record<string, unknown>) { }
+ * // Method-level with instance
+ * @Tool({ name: 'large_query' })
+ * @UseInterceptors(new DataSpilloverInterceptor({ maxPayloadBytes: 10240 }))
+ * async getLargeData() { ... }
+ *
+ * // Class-level with factory
+ * @Controller()
+ * @UseInterceptors(DataSpilloverInterceptor.configure({ maxPayloadBytes: 20480 }))
+ * export class EnterpriseDataController { ... }
  * ```
  */
-export declare function UseInterceptors(...interceptors: InterceptorConstructor[]): MethodDecorator;
+export declare function UseInterceptors(...interceptors: InterceptorType[]): (target: any, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => any;
 /**
- * Get interceptors for a method
+ * Retrieves interceptors for a method, combining class-level and method-level metadata.
  */
-export declare function getInterceptorMetadata(target: object, propertyKey: string | symbol): InterceptorConstructor[];
+export declare function getInterceptorMetadata(target: object, propertyKey?: string | symbol): InterceptorType[];
 /**
  * Check if a class is marked as an interceptor
  */

package/dist/core/interceptors/interceptor.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.decorator.d.ts","sourceRoot":"","sources":["../../../src/core/interceptors/interceptor.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAKpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAI5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,YAAY,EAAE,sBAAsB,EAAE,GAAG,eAAe,CAU1F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,sBAAsB,EAAE,CAE7G;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}
+{"version":3,"file":"interceptor.decorator.d.ts","sourceRoot":"","sources":["../../../src/core/interceptors/interceptor.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,eAAO,MAAM,eAAe,2BAA2B,CAAC;AACxD,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAI5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,GAAG,YAAY,EAAE,eAAe,EAAE,IAC/C,QAAQ,GAAG,EAAE,cAAc,MAAM,GAAG,MAAM,EAAE,aAAa,kBAAkB,SAa7F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,EAAE,CAYvG;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/core/interceptors/interceptor.decorator.js

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
-const INTERCEPTOR_KEY = 'nitrostack:interceptor';
-const IS_INTERCEPTOR_KEY = 'nitrostack:is_interceptor';
+export const INTERCEPTOR_KEY = 'nitrostack:interceptor';
+export const IS_INTERCEPTOR_KEY = 'nitrostack:is_interceptor';
 /**
  * Marks a class as an interceptor
  *
@@ -21,26 +21,51 @@ export function Interceptor() {
     };
 }
 /**
- * Apply interceptors to a tool method
+ * Apply interceptors to a tool method or to an entire controller class.
+ * Supports both class constructors and pre-configured instances.
  *
  * @example
  * ```typescript
- * @Tool({ name: 'get_user', ... })
- * @UseInterceptors(TransformInterceptor, CacheInterceptor)
- * async getUser(input: Record<string, unknown>) { }
+ * // Method-level with instance
+ * @Tool({ name: 'large_query' })
+ * @UseInterceptors(new DataSpilloverInterceptor({ maxPayloadBytes: 10240 }))
+ * async getLargeData() { ... }
+ *
+ * // Class-level with factory
+ * @Controller()
+ * @UseInterceptors(DataSpilloverInterceptor.configure({ maxPayloadBytes: 20480 }))
+ * export class EnterpriseDataController { ... }
  * ```
  */
 export function UseInterceptors(...interceptors) {
-    return (target, propertyKey, descriptor) => {
-        const existingInterceptors = Reflect.getMetadata(INTERCEPTOR_KEY, target, propertyKey) || [];
-        Reflect.defineMetadata(INTERCEPTOR_KEY, [...existingInterceptors, ...interceptors], target, propertyKey);
+    return function (target, propertyKey, descriptor) {
+        if (descriptor && propertyKey) {
+            // Method-level decorator
+            const existing = Reflect.getMetadata(INTERCEPTOR_KEY, target, propertyKey) || [];
+            Reflect.defineMetadata(INTERCEPTOR_KEY, [...existing, ...interceptors], target, propertyKey);
+            return descriptor;
+        }
+        else {
+            // Class-level decorator (target is constructor)
+            const existing = Reflect.getMetadata(INTERCEPTOR_KEY, target) || [];
+            Reflect.defineMetadata(INTERCEPTOR_KEY, [...existing, ...interceptors], target);
+            return target;
+        }
     };
 }
 /**
- * Get interceptors for a method
+ * Retrieves interceptors for a method, combining class-level and method-level metadata.
  */
 export function getInterceptorMetadata(target, propertyKey) {
-    return Reflect.getMetadata(INTERCEPTOR_KEY, target, propertyKey) || [];
+    const methodInterceptors = propertyKey
+        ? Reflect.getMetadata(INTERCEPTOR_KEY, target, propertyKey) || []
+        : [];
+    // Class constructor metadata
+    const ctor = typeof target === 'function' ? target : target?.constructor;
+    const classInterceptors = ctor
+        ? Reflect.getMetadata(INTERCEPTOR_KEY, ctor) || []
+        : [];
+    return [...classInterceptors, ...methodInterceptors];
 }
 /**
  * Check if a class is marked as an interceptor

package/dist/core/interceptors/interceptor.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.decorator.js","sourceRoot":"","sources":["../../../src/core/interceptors/interceptor.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,MAAM,eAAe,GAAG,wBAAwB,CAAC;AACjD,MAAM,kBAAkB,GAAG,2BAA2B,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,MAAc,EAAE,EAAE;QACxB,OAAO,CAAC,cAAc,CAAC,kBAAkB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAG,YAAsC;IACvE,OAAO,CAAC,MAAc,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;QACtF,MAAM,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QAC7F,OAAO,CAAC,cAAc,CACpB,eAAe,EACf,CAAC,GAAG,oBAAoB,EAAE,GAAG,YAAY,CAAC,EAC1C,MAAM,EACN,WAAW,CACZ,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,WAA4B;IACjF,OAAO,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AAClE,CAAC"}
+{"version":3,"file":"interceptor.decorator.js","sourceRoot":"","sources":["../../../src/core/interceptors/interceptor.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,MAAM,CAAC,MAAM,eAAe,GAAG,wBAAwB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,2BAA2B,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,MAAc,EAAE,EAAE;QACxB,OAAO,CAAC,cAAc,CAAC,kBAAkB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,GAAG,YAA+B;IAChE,OAAO,UAAU,MAAW,EAAE,WAA6B,EAAE,UAA+B;QAC1F,IAAI,UAAU,IAAI,WAAW,EAAE,CAAC;YAC9B,yBAAyB;YACzB,MAAM,QAAQ,GAAsB,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;YACpG,OAAO,CAAC,cAAc,CAAC,eAAe,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;YAC7F,OAAO,UAAU,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,gDAAgD;YAChD,MAAM,QAAQ,GAAsB,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YACvF,OAAO,CAAC,cAAc,CAAC,eAAe,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;YAChF,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,WAA6B;IAClF,MAAM,kBAAkB,GAAsB,WAAW;QACvD,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE;QACjE,CAAC,CAAC,EAAE,CAAC;IAEP,6BAA6B;IAC7B,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,MAAc,EAAE,WAAW,CAAC;IAClF,MAAM,iBAAiB,GAAsB,IAAI;QAC/C,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE;QAClD,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO,CAAC,GAAG,iBAAiB,EAAE,GAAG,kBAAkB,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;AAClE,CAAC"}

package/dist/core/interceptors/interceptor.interface.d.ts

@@ -28,4 +28,8 @@ export interface InterceptorInterface {
  * Interceptor constructor type
  */
 export type InterceptorConstructor = new (...args: unknown[]) => InterceptorInterface;
+/**
+ * Union type permitting either a class constructor or an instantiated/configured instance.
+ */
+export type InterceptorType = InterceptorConstructor | InterceptorInterface;
 //# sourceMappingURL=interceptor.interface.d.ts.map

package/dist/core/interceptors/interceptor.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.interface.d.ts","sourceRoot":"","sources":["../../../src/core/interceptors/interceptor.interface.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtF;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,oBAAoB,CAAC"}
+{"version":3,"file":"interceptor.interface.d.ts","sourceRoot":"","sources":["../../../src/core/interceptors/interceptor.interface.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtF;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,oBAAoB,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC"}

package/dist/core/interceptors/spillover/fs-spillover.store.d.ts

@@ -0,0 +1,54 @@
+import { SpilloverRecord, SpilloverStore } from './spillover-store.interface.js';
+export interface FsSpilloverOptions {
+    storageDir?: string;
+    sweepIntervalSeconds?: number;
+    /** Total bytes retained on disk (default: 512MB). A single record larger than this is refused. */
+    maxSizeBytes?: number;
+}
+/**
+ * Filesystem spillover store.
+ *
+ * Directory mode 0o700 and file mode 0o600 are enforced on Unix. Windows ignores
+ * those bits, so a shared temp directory is not private there; set `storageDir`
+ * to a directory only this process can read.
+ */
+export declare class FsSpilloverStore implements SpilloverStore {
+    private storageDir;
+    private readonly explicitDir;
+    private readonly maxSizeBytes;
+    private readonly sweepTimer;
+    private initialized;
+    private usageReady;
+    private currentSizeBytes;
+    /** Serializes saves so two writers cannot both pass the capacity check. */
+    private writeChain;
+    constructor(options?: FsSpilloverOptions);
+    private ensureDir;
+    /**
+     * Refuse a symlink. mkdir({ recursive: true }) follows one, and chmod follows
+     * it too, so a planted link would receive the spilled files.
+     */
+    private assertRealDirectory;
+    private sanitizeId;
+    private getFilePath;
+    getStorageDir(): string;
+    getMaxSizeBytes(): number;
+    getCurrentSizeBytes(): number;
+    private enqueue;
+    save(id: string, data: string, mimeType: string, ttlSeconds: number, sessionId?: string): Promise<SpilloverRecord>;
+    private writeRecord;
+    get(id: string): Promise<SpilloverRecord | undefined>;
+    delete(id: string): Promise<boolean>;
+    private unlinkId;
+    private deleteIfStillExpired;
+    cleanup(): Promise<number>;
+    private cleanupNow;
+    private ensureUsage;
+    private fileSize;
+    /** Deletes the oldest payload file, excluding the path about to be replaced. */
+    private evictOldestFile;
+    /** First bytes of a record. `expiresAt` is written before the payload. */
+    private readExpiresAt;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=fs-spillover.store.d.ts.map

package/dist/core/interceptors/spillover/fs-spillover.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-spillover.store.d.ts","sourceRoot":"","sources":["../../../../src/core/interceptors/spillover/fs-spillover.store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAKD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAK;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,UAAU,CAAoC;gBAE1C,OAAO,GAAE,kBAAuB;YAiB9B,SAAS;IAavB;;;OAGG;YACW,mBAAmB;IA8BjC,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;IAInB,aAAa,IAAI,MAAM;IAIvB,eAAe,IAAI,MAAM;IAIzB,mBAAmB,IAAI,MAAM;IAI7B,OAAO,CAAC,OAAO;IAST,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YAI1G,WAAW;IA0DnB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAkBrD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAI5B,QAAQ;YAYR,oBAAoB;IAO5B,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;YAIlB,UAAU;YA4CV,WAAW;YAYX,QAAQ;IAKtB,gFAAgF;YAClE,eAAe;IAmB7B,0EAA0E;YAC5D,aAAa;IAcrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}