duckpond 0.2.1 → 0.4.0

package/dist/DuckPond.d.ts

@@ -1,100 +1,80 @@
-import { DuckDBConnection } from '@duckdb/node-api';
-import { DuckPondConfig, AsyncDuckPondResult, UserStats, ListUsersResult } from './types.js';
-import 'functype/either';
-import 'functype/list';
+import { AsyncDuckPondResult, DuckPondConfig, DuckPondResult, ListUsersResult, UserStats } from "./types.js";
+import { DuckDBConnection } from "@duckdb/node-api";
 
-/**
- * DuckPond - Multi-tenant DuckDB manager with R2/S3 storage
- *
- * Manages per-user DuckDB instances with:
- * - LRU caching for active users
- * - R2/S3 object storage integration
- * - Functional error handling with functype Either
- * - Automatic resource cleanup
- *
- * @example
- * ```typescript
- * const pond = new DuckPond({
- *   r2: {
- *     accountId: 'xxx',
- *     accessKeyId: 'yyy',
- *     secretAccessKey: 'zzz',
- *     bucket: 'my-bucket'
- *   }
- * })
- *
- * await pond.init()
- *
- * const result = await pond.query('user123', 'SELECT * FROM orders')
- * result.fold(
- *   error => console.error('Query failed:', error),
- *   rows => console.log('Results:', rows)
- * )
- * ```
- */
+//#region src/DuckPond.d.ts
 declare class DuckPond {
-    private instance;
-    private cache;
-    private config;
-    private evictionTimer;
-    private initialized;
-    constructor(config: DuckPondConfig);
-    /**
-     * Initialize DuckPond
-     * Must be called before any other operations
-     */
-    init(): AsyncDuckPondResult<void>;
-    /**
-     * Configure R2/S3 access and DuckDB extensions
-     */
-    private setupCloudStorage;
-    /**
-     * Get a connection for a user
-     * Loads from cache or attaches new database
-     */
-    getUserConnection(userId: string): AsyncDuckPondResult<DuckDBConnection>;
-    /**
-     * Attach a user's database based on storage strategy
-     */
-    private attachUserDatabase;
-    /**
-     * Execute a SQL query for a user
-     * Returns Either<Error, results>
-     */
-    query<T = unknown>(userId: string, sql: string): AsyncDuckPondResult<T[]>;
-    /**
-     * Execute SQL without returning results (DDL, DML)
-     */
-    execute(userId: string, sql: string): AsyncDuckPondResult<void>;
-    /**
-     * Detach a user's database and free resources
-     */
-    detachUser(userId: string): AsyncDuckPondResult<void>;
-    /**
-     * Evict the least recently used user
-     */
-    private evictLRU;
-    /**
-     * Start background timer to evict idle users
-     */
-    private startEvictionTimer;
-    /**
-     * Check if a user is currently attached
-     */
-    isAttached(userId: string): boolean;
-    /**
-     * Get statistics about a user's database
-     */
-    getUserStats(userId: string): AsyncDuckPondResult<UserStats>;
-    /**
-     * Get list of all currently cached users
-     * Returns a List of user IDs and cache statistics
-     */
-    listUsers(): ListUsersResult;
-    /**
-     * Close DuckPond and cleanup all resources
-     */
-    close(): AsyncDuckPondResult<void>;
+  private instance;
+  private cache;
+  private config;
+  private initialized;
+  constructor(config: DuckPondConfig);
+  /**
+   * Cleanup resources when a user is evicted from cache
+   * Called automatically by LRU cache dispose callback
+   */
+  private cleanupUserResources;
+  /**
+   * Initialize DuckPond
+   * Must be called before any other operations
+   */
+  init(): AsyncDuckPondResult<void>;
+  /**
+   * Ensure the data directory exists
+   */
+  private ensureDataDir;
+  /**
+   * Get the database file path for a user
+   */
+  private getUserDbPath;
+  /**
+   * Configure R2/S3 access and DuckDB extensions
+   */
+  private setupCloudStorage;
+  /**
+   * Get a connection for a user
+   * Loads from cache or creates new database
+   */
+  getUserConnection(userId: string): AsyncDuckPondResult<DuckDBConnection>;
+  /**
+   * Create a local file-based database connection for a user
+   */
+  private createLocalUserConnection;
+  /**
+   * Attach a user's database based on storage strategy
+   */
+  private attachUserDatabase;
+  /**
+   * Execute a SQL query for a user
+   * Returns Either<Error, results>
+   */
+  query<T = unknown>(userId: string, sql: string): AsyncDuckPondResult<T[]>;
+  /**
+   * Execute SQL without returning results (DDL, DML)
+   */
+  execute(userId: string, sql: string): AsyncDuckPondResult<void>;
+  /**
+   * Detach a user's database and free resources
+   * Cleanup happens automatically via the cache dispose callback
+   */
+  detachUser(userId: string): DuckPondResult<void>;
+  /**
+   * Check if a user is currently attached
+   */
+  isAttached(userId: string): boolean;
+  /**
+   * Get statistics about a user's database
+   */
+  getUserStats(userId: string): AsyncDuckPondResult<UserStats>;
+  /**
+   * Get list of all currently cached users
+   * Returns a List of user IDs and cache statistics
+   */
+  listUsers(): ListUsersResult;
+  /**
+   * Close DuckPond and cleanup all resources
+   */
+  close(): DuckPondResult<void>;
 }
-
+//#endregion
 export { DuckPond };
+//# sourceMappingURL=DuckPond.d.ts.map

package/dist/DuckPond.js

@@ -1,2 +1,30 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkMLZHFU2Bjs = require('./chunk-MLZHFU2B.js');require('./chunk-J2OQ62DV.js');require('./chunk-MZTKR3LR.js');require('./chunk-2PPSIE57.js');require('./chunk-Q6UFPTQC.js');require('./chunk-5XGN7UAV.js');exports.DuckPond = _chunkMLZHFU2Bjs.a;
+import{loggers as e}from"./utils/logger.js";import{n as t,t as n}from"./LRUCache-Bg_8n4IH.js";import{ErrorCode as r}from"./types.js";import{Errors as i,success as a,toDuckPondError as o}from"./utils/errors.js";import{DuckDBInstance as s}from"@duckdb/node-api";import*as c from"fs";import{Left as l,Option as u}from"functype";import*as d from"path";const f=e.main;var p=class{constructor(e){t(this,`instance`,u.none()),t(this,`cache`,void 0),t(this,`config`,void 0),t(this,`initialized`,!1),this.config={memoryLimit:e.memoryLimit||`4GB`,threads:e.threads||4,tempDir:e.tempDir||`/tmp/duckpond`,maxActiveUsers:e.maxActiveUsers||10,evictionTimeout:e.evictionTimeout||3e5,cacheType:e.cacheType||`disk`,cacheDir:e.cacheDir||`/tmp/duckpond-cache`,strategy:e.strategy||`parquet`,dataDir:e.dataDir,r2:e.r2,s3:e.s3},this.cache=new n({maxSize:this.config.maxActiveUsers,ttl:this.config.evictionTimeout,dispose:(e,t,n)=>{this.cleanupUserResources(e,t,n)}}),f(`DuckPond created with config:`,{memoryLimit:this.config.memoryLimit,threads:this.config.threads,maxActiveUsers:this.config.maxActiveUsers,strategy:this.config.strategy,dataDir:this.config.dataDir,storageMode:this.config.dataDir?`local`:this.config.r2?`r2`:this.config.s3?`s3`:`memory`})}cleanupUserResources(e,t,n){if(f(`Cleaning up user ${t} (reason: ${n})`),this.config.dataDir&&e.instance)try{e.instance.closeSync(),f(`Closed local database instance for user: ${t}`)}catch(e){f(`Error closing instance for user ${t}:`,e)}this.config.strategy===`duckdb`&&!this.config.dataDir&&e.attached&&e.connection.run(`DETACH user_${t}`).then(()=>f(`Detached cloud database for user: ${t}`)).catch(e=>f(`Error detaching database for user ${t}:`,e))}async init(){if(this.initialized)return f(`Already initialized`),a(void 0);f(`Initializing DuckPond...`);try{if(this.config.dataDir&&(await this.ensureDataDir(),f(`Local storage enabled: ${this.config.dataDir}`)),!this.config.dataDir){this.instance=u(await s.create(`:memory:`));let e=await this.setupCloudStorage();if(e.isLeft()){let t=e.fold(e=>e,()=>null);throw Error(t?.message||`Cloud storage setup failed`)}}return this.initialized=!0,f(`DuckPond initialized successfully`),a(void 0)}catch(e){return l(o(e,r.CONNECTION_FAILED))}}async ensureDataDir(){if(this.config.dataDir)try{await c.promises.mkdir(this.config.dataDir,{recursive:!0}),f(`Data directory ready: ${this.config.dataDir}`)}catch(e){throw f(`Failed to create data directory: ${e}`),e}}getUserDbPath(e){if(!this.config.dataDir)throw Error(`dataDir not configured`);let t=e.replace(/[^a-zA-Z0-9_-]/g,`_`);return d.join(this.config.dataDir,`${t}.duckdb`)}async setupCloudStorage(){if(this.instance.isNone())return i.notInitialized();let e=await this.instance.fold(()=>{throw Error(`Unexpected: instance should be Some`)},e=>e).connect();try{if(this.config.r2)f(`Configuring R2 access`),await e.run(`
+          CREATE SECRET r2_secret (
+            TYPE R2,
+            ACCOUNT_ID '${this.config.r2.accountId}',
+            ACCESS_KEY_ID '${this.config.r2.accessKeyId}',
+            SECRET_ACCESS_KEY '${this.config.r2.secretAccessKey}'
+          );
+        `);else if(this.config.s3){f(`Configuring S3 access`);let t=this.config.s3.endpoint?`ENDPOINT '${this.config.s3.endpoint}',`:``;await e.run(`
+          CREATE SECRET s3_secret (
+            TYPE S3,
+            REGION '${this.config.s3.region}',
+            ${t}
+            ACCESS_KEY_ID '${this.config.s3.accessKeyId}',
+            SECRET_ACCESS_KEY '${this.config.s3.secretAccessKey}'
+          );
+        `)}return(this.config.r2||this.config.s3)&&(await e.run(`
+          INSTALL httpfs;
+          LOAD httpfs;
+          INSTALL cache_httpfs;
+          LOAD cache_httpfs;
+        `),await e.run(`
+          SET cache_httpfs_type='${this.config.cacheType}';
+        `)),await e.run(`
+        SET memory_limit='${this.config.memoryLimit}';
+        SET threads=${this.config.threads};
+      `),f(`Cloud storage configured successfully`),a(void 0)}catch(e){return i.r2ConnectionError(`Failed to setup cloud storage`,e)}}async getUserConnection(e){if(!this.initialized)return i.notInitialized();let t=this.cache.get(e);if(t.isSome())return f(`Using cached connection for user: ${e}`),t.fold(()=>i.userNotFound(e),e=>Promise.resolve(a(e.connection)));if(f(`Loading database for user: ${e}`),this.config.dataDir)return this.createLocalUserConnection(e);if(this.instance.isNone())return i.notInitialized();let n=await this.instance.fold(()=>{throw Error(`Unexpected: instance should be Some`)},e=>e).connect(),r=await this.attachUserDatabase(n,e);return r.isLeft()?r:(this.cache.set(e,{userId:e,connection:n,lastAccess:new Date,attached:!0}),f(`Loaded database for user: ${e}`),a(n))}async createLocalUserConnection(e){try{let t=this.getUserDbPath(e);f(`Creating/opening local database for user ${e}: ${t}`);let n=await s.create(t),r=await n.connect();return await r.run(`
+        SET memory_limit='${this.config.memoryLimit}';
+        SET threads=${this.config.threads};
+      `),this.cache.set(e,{userId:e,connection:r,lastAccess:new Date,attached:!0,instance:n}),f(`Local database ready for user: ${e}`),a(r)}catch(e){return l(o(e,r.CONNECTION_FAILED))}}async attachUserDatabase(e,t){try{let n=this.config.r2?.bucket||this.config.s3?.bucket,r=this.config.r2?`r2`:`s3`;if(this.config.strategy===`duckdb`){let i=`${r}://${n}/users/${t}/database.duckdb`;await e.run(`ATTACH '${i}' AS user_${t} (READ_ONLY);`),f(`Attached .duckdb file for user: ${t}`)}return a(void 0)}catch(e){return i.storageError(`Failed to attach user database`,e)}}async query(e,t){let n=await this.getUserConnection(e);if(n.isLeft())return n;let i=n.fold(()=>{throw Error(`Unexpected: connection should be Right`)},e=>e);try{return a(await(await i.run(t)).getRowObjects())}catch(e){return l(o(e,r.QUERY_EXECUTION_ERROR))}}async execute(e,t){let n=await this.getUserConnection(e);if(n.isLeft())return n;let i=n.fold(()=>{throw Error(`Unexpected: connection should be Right`)},e=>e);try{return await i.run(t),a(void 0)}catch(e){return l(o(e,r.QUERY_EXECUTION_ERROR))}}detachUser(e){return this.cache.has(e)?(f(`Detaching user: ${e}`),this.cache.delete(e),a(void 0)):(f(`User not attached: ${e}`),a(void 0))}isAttached(e){return this.cache.has(e)}async getUserStats(e){let t=this.cache.get(e);return a({userId:e,attached:t.isSome(),lastAccess:t.fold(()=>new Date(0),e=>e.lastAccess),memoryUsage:t.fold(()=>0,e=>e.memoryUsage||0),storageUsage:0,queryCount:0})}listUsers(){let e=this.cache.getStats();return{users:this.cache.keys(),count:e.size,maxActiveUsers:e.maxSize,utilizationPercent:e.utilizationPercent}}close(){return f(`Closing DuckPond...`),this.cache.clear(),this.instance=u.none(),this.initialized=!1,f(`DuckPond closed`),a(void 0)}};export{p as DuckPond};
 //# sourceMappingURL=DuckPond.js.map

package/dist/DuckPond.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/jordanburke/IdeaProjects/duckpond/dist/DuckPond.js"],"names":[],"mappings":"AAAA,+HAAkC,+BAA4B,+BAA4B,+BAA4B,+BAA4B,+BAA4B,sCAAsB","file":"/Users/jordanburke/IdeaProjects/duckpond/dist/DuckPond.js"}
+{"version":3,"file":"DuckPond.js","names":[],"sources":["../src/DuckPond.ts"],"sourcesContent":["import { type DuckDBConnection, DuckDBInstance } from \"@duckdb/node-api\"\nimport * as fs from \"fs\"\nimport { Either, Left, Right } from \"functype\"\nimport { Option } from \"functype\"\nimport { Try } from \"functype\"\nimport * as path from \"path\"\n\nimport { LRUCache } from \"./cache/LRUCache\"\nimport type {\n  AsyncDuckPondResult,\n  CreateUserOptions,\n  DuckPondConfig,\n  DuckPondResult,\n  ListUsersResult,\n  ResolvedConfig,\n  Schema,\n  UserDatabase,\n  UserStats,\n} from \"./types\"\nimport { ErrorCode } from \"./types\"\nimport { Errors, success, toDuckPondError } from \"./utils/errors\"\nimport { loggers } from \"./utils/logger\"\n\nconst log = loggers.main\n\n/**\n * DuckPond - Multi-tenant DuckDB manager with R2/S3 storage\n *\n * Manages per-user DuckDB instances with:\n * - LRU caching for active users\n * - R2/S3 object storage integration\n * - Functional error handling with functype Either\n * - Automatic resource cleanup\n *\n * @example\n * ```typescript\n * const pond = new DuckPond({\n *   r2: {\n *     accountId: 'xxx',\n *     accessKeyId: 'yyy',\n *     secretAccessKey: 'zzz',\n *     bucket: 'my-bucket'\n *   }\n * })\n *\n * await pond.init()\n *\n * const result = await pond.query('user123', 'SELECT * FROM orders')\n * result.fold(\n *   error => console.error('Query failed:', error),\n *   rows => console.log('Results:', rows)\n * )\n * ```\n */\n/** Extended user database with per-user instance for local storage */\ninterface UserDatabaseWithInstance extends UserDatabase {\n  instance?: DuckDBInstance\n}\n\nexport class DuckPond {\n  private instance: Option<DuckDBInstance> = Option.none()\n  private cache: LRUCache<UserDatabaseWithInstance>\n  private config: ResolvedConfig\n  private initialized = false\n\n  constructor(config: DuckPondConfig) {\n    // Apply defaults\n    this.config = {\n      memoryLimit: config.memoryLimit || \"4GB\",\n      threads: config.threads || 4,\n      tempDir: config.tempDir || \"/tmp/duckpond\",\n      maxActiveUsers: config.maxActiveUsers || 10,\n      evictionTimeout: config.evictionTimeout || 300000,\n      cacheType: config.cacheType || \"disk\",\n      cacheDir: config.cacheDir || \"/tmp/duckpond-cache\",\n      strategy: config.strategy || \"parquet\",\n      dataDir: config.dataDir,\n      r2: config.r2,\n      s3: config.s3,\n    }\n\n    // Create cache with TTL-based eviction and automatic cleanup\n    this.cache = new LRUCache({\n      maxSize: this.config.maxActiveUsers,\n      ttl: this.config.evictionTimeout,\n      dispose: (userDb, userId, reason) => {\n        this.cleanupUserResources(userDb, userId, reason)\n      },\n    })\n\n    log(\"DuckPond created with config:\", {\n      memoryLimit: this.config.memoryLimit,\n      threads: this.config.threads,\n      maxActiveUsers: this.config.maxActiveUsers,\n      strategy: this.config.strategy,\n      dataDir: this.config.dataDir,\n      storageMode: this.config.dataDir ? \"local\" : this.config.r2 ? \"r2\" : this.config.s3 ? \"s3\" : \"memory\",\n    })\n  }\n\n  /**\n   * Cleanup resources when a user is evicted from cache\n   * Called automatically by LRU cache dispose callback\n   */\n  private cleanupUserResources(\n    userDb: UserDatabaseWithInstance,\n    userId: string,\n    reason: \"evict\" | \"set\" | \"delete\" | \"stale\",\n  ): void {\n    log(`Cleaning up user ${userId} (reason: ${reason})`)\n\n    // For local storage, close the per-user instance synchronously\n    if (this.config.dataDir && userDb.instance) {\n      try {\n        userDb.instance.closeSync()\n        log(`Closed local database instance for user: ${userId}`)\n      } catch (error) {\n        log(`Error closing instance for user ${userId}:`, error)\n      }\n    }\n\n    // For cloud duckdb strategy, detach the database (fire-and-forget)\n    if (this.config.strategy === \"duckdb\" && !this.config.dataDir && userDb.attached) {\n      userDb.connection\n        .run(`DETACH user_${userId}`)\n        .then(() => log(`Detached cloud database for user: ${userId}`))\n        .catch((error) => log(`Error detaching database for user ${userId}:`, error))\n    }\n  }\n\n  /**\n   * Initialize DuckPond\n   * Must be called before any other operations\n   */\n  async init(): AsyncDuckPondResult<void> {\n    if (this.initialized) {\n      log(\"Already initialized\")\n      return success(undefined)\n    }\n\n    log(\"Initializing DuckPond...\")\n\n    try {\n      // Create dataDir if local storage is enabled\n      if (this.config.dataDir) {\n        await this.ensureDataDir()\n        log(`Local storage enabled: ${this.config.dataDir}`)\n      }\n\n      // For cloud storage or memory mode, create a shared instance\n      // For local storage, we create per-user instances in getUserConnection\n      if (!this.config.dataDir) {\n        const instance = await DuckDBInstance.create(\":memory:\")\n        this.instance = Option(instance)\n\n        // Setup cloud storage\n        const setupResult = await this.setupCloudStorage()\n        if (setupResult.isLeft()) {\n          const error = setupResult.fold(\n            (err) => err,\n            () => null,\n          )\n          throw new Error(error?.message || \"Cloud storage setup failed\")\n        }\n      }\n\n      this.initialized = true\n      log(\"DuckPond initialized successfully\")\n      return success(undefined)\n    } catch (error) {\n      return Left(toDuckPondError(error, ErrorCode.CONNECTION_FAILED))\n    }\n  }\n\n  /**\n   * Ensure the data directory exists\n   */\n  private async ensureDataDir(): Promise<void> {\n    if (!this.config.dataDir) return\n\n    try {\n      await fs.promises.mkdir(this.config.dataDir, { recursive: true })\n      log(`Data directory ready: ${this.config.dataDir}`)\n    } catch (error) {\n      log(`Failed to create data directory: ${error}`)\n      throw error\n    }\n  }\n\n  /**\n   * Get the database file path for a user\n   */\n  private getUserDbPath(userId: string): string {\n    if (!this.config.dataDir) {\n      throw new Error(\"dataDir not configured\")\n    }\n    // Sanitize userId for filesystem safety\n    const safeUserId = userId.replace(/[^a-zA-Z0-9_-]/g, \"_\")\n    return path.join(this.config.dataDir, `${safeUserId}.duckdb`)\n  }\n\n  /**\n   * Configure R2/S3 access and DuckDB extensions\n   */\n  private async setupCloudStorage(): AsyncDuckPondResult<void> {\n    if (this.instance.isNone()) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return Errors.notInitialized() as any\n    }\n\n    const instance = this.instance.fold(\n      () => {\n        throw new Error(\"Unexpected: instance should be Some\")\n      },\n      (inst) => inst,\n    )\n\n    const conn = await instance.connect()\n\n    try {\n      // Create secret for R2 or S3\n      if (this.config.r2) {\n        log(\"Configuring R2 access\")\n        await conn.run(`\n          CREATE SECRET r2_secret (\n            TYPE R2,\n            ACCOUNT_ID '${this.config.r2.accountId}',\n            ACCESS_KEY_ID '${this.config.r2.accessKeyId}',\n            SECRET_ACCESS_KEY '${this.config.r2.secretAccessKey}'\n          );\n        `)\n      } else if (this.config.s3) {\n        log(\"Configuring S3 access\")\n        const endpoint = this.config.s3.endpoint ? `ENDPOINT '${this.config.s3.endpoint}',` : \"\"\n        await conn.run(`\n          CREATE SECRET s3_secret (\n            TYPE S3,\n            REGION '${this.config.s3.region}',\n            ${endpoint}\n            ACCESS_KEY_ID '${this.config.s3.accessKeyId}',\n            SECRET_ACCESS_KEY '${this.config.s3.secretAccessKey}'\n          );\n        `)\n      }\n\n      // Install extensions only if R2/S3 is configured\n      if (this.config.r2 || this.config.s3) {\n        await conn.run(`\n          INSTALL httpfs;\n          LOAD httpfs;\n          INSTALL cache_httpfs;\n          LOAD cache_httpfs;\n        `)\n\n        // Configure cache\n        await conn.run(`\n          SET cache_httpfs_type='${this.config.cacheType}';\n        `)\n      }\n\n      // Configure performance settings\n      await conn.run(`\n        SET memory_limit='${this.config.memoryLimit}';\n        SET threads=${this.config.threads};\n      `)\n\n      log(\"Cloud storage configured successfully\")\n      return success(undefined)\n    } catch (error) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return Errors.r2ConnectionError(\"Failed to setup cloud storage\", error as Error) as any\n    }\n  }\n\n  /**\n   * Get a connection for a user\n   * Loads from cache or creates new database\n   */\n  async getUserConnection(userId: string): AsyncDuckPondResult<DuckDBConnection> {\n    if (!this.initialized) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return Errors.notInitialized() as any\n    }\n\n    // Check cache\n    const cached = this.cache.get(userId)\n    if (cached.isSome()) {\n      log(`Using cached connection for user: ${userId}`)\n      return cached.fold(\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        (): AsyncDuckPondResult<DuckDBConnection> => Errors.userNotFound(userId) as any,\n        (userDb): AsyncDuckPondResult<DuckDBConnection> => Promise.resolve(success(userDb.connection)),\n      )\n    }\n\n    log(`Loading database for user: ${userId}`)\n\n    // Note: LRU cache automatically evicts when at capacity via dispose callback\n\n    // Local storage mode: create per-user file-based instance\n    if (this.config.dataDir) {\n      return this.createLocalUserConnection(userId)\n    }\n\n    // Cloud/memory mode: use shared instance\n    if (this.instance.isNone()) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return Errors.notInitialized() as any\n    }\n\n    const instance = this.instance.fold(\n      () => {\n        throw new Error(\"Unexpected: instance should be Some\")\n      },\n      (inst) => inst,\n    )\n\n    const conn = await instance.connect()\n\n    // Attach user's database (strategy-dependent)\n    const attachResult = await this.attachUserDatabase(conn, userId)\n    if (attachResult.isLeft()) {\n      // Note: DuckDB connections are managed by the instance, no need to close\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return attachResult as any\n    }\n\n    // Add to cache\n    this.cache.set(userId, {\n      userId,\n      connection: conn,\n      lastAccess: new Date(),\n      attached: true,\n    })\n\n    log(`Loaded database for user: ${userId}`)\n    return success(conn)\n  }\n\n  /**\n   * Create a local file-based database connection for a user\n   */\n  private async createLocalUserConnection(userId: string): AsyncDuckPondResult<DuckDBConnection> {\n    try {\n      const dbPath = this.getUserDbPath(userId)\n      log(`Creating/opening local database for user ${userId}: ${dbPath}`)\n\n      // Create per-user DuckDB instance with file path\n      const userInstance = await DuckDBInstance.create(dbPath)\n      const conn = await userInstance.connect()\n\n      // Configure performance settings\n      await conn.run(`\n        SET memory_limit='${this.config.memoryLimit}';\n        SET threads=${this.config.threads};\n      `)\n\n      // Add to cache with instance reference\n      this.cache.set(userId, {\n        userId,\n        connection: conn,\n        lastAccess: new Date(),\n        attached: true,\n        instance: userInstance,\n      })\n\n      log(`Local database ready for user: ${userId}`)\n      return success(conn)\n    } catch (error) {\n      return Left(toDuckPondError(error, ErrorCode.CONNECTION_FAILED))\n    }\n  }\n\n  /**\n   * Attach a user's database based on storage strategy\n   */\n  private async attachUserDatabase(conn: DuckDBConnection, userId: string): AsyncDuckPondResult<void> {\n    try {\n      const bucket = this.config.r2?.bucket || this.config.s3?.bucket\n      const protocol = this.config.r2 ? \"r2\" : \"s3\"\n\n      if (this.config.strategy === \"duckdb\") {\n        // Attach .duckdb file (read-only)\n        const dbPath = `${protocol}://${bucket}/users/${userId}/database.duckdb`\n        await conn.run(`ATTACH '${dbPath}' AS user_${userId} (READ_ONLY);`)\n        log(`Attached .duckdb file for user: ${userId}`)\n      }\n      // For parquet strategy, no explicit attach needed\n      return success(undefined)\n    } catch (error) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return Errors.storageError(\"Failed to attach user database\", error as Error) as any\n    }\n  }\n\n  /**\n   * Execute a SQL query for a user\n   * Returns Either<Error, results>\n   */\n  async query<T = unknown>(userId: string, sql: string): AsyncDuckPondResult<T[]> {\n    const connResult = await this.getUserConnection(userId)\n\n    if (connResult.isLeft()) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return connResult as any\n    }\n\n    const conn = connResult.fold(\n      () => {\n        throw new Error(\"Unexpected: connection should be Right\")\n      },\n      (c) => c,\n    )\n\n    try {\n      const resultObj = await conn.run(sql)\n      // DuckDB node-api: use getRowObjects() to get rows as objects\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const rows = (await (resultObj as any).getRowObjects()) as T[]\n\n      return success(rows)\n    } catch (error) {\n      return Left(toDuckPondError(error, ErrorCode.QUERY_EXECUTION_ERROR))\n    }\n  }\n\n  /**\n   * Execute SQL without returning results (DDL, DML)\n   */\n  async execute(userId: string, sql: string): AsyncDuckPondResult<void> {\n    const connResult = await this.getUserConnection(userId)\n\n    if (connResult.isLeft()) {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      return connResult as any\n    }\n\n    const conn = connResult.fold(\n      () => {\n        throw new Error(\"Unexpected: connection should be Right\")\n      },\n      (c) => c,\n    )\n\n    try {\n      await conn.run(sql)\n      return success(undefined)\n    } catch (error) {\n      return Left(toDuckPondError(error, ErrorCode.QUERY_EXECUTION_ERROR))\n    }\n  }\n\n  /**\n   * Detach a user's database and free resources\n   * Cleanup happens automatically via the cache dispose callback\n   */\n  detachUser(userId: string): DuckPondResult<void> {\n    if (!this.cache.has(userId)) {\n      log(`User not attached: ${userId}`)\n      return success(undefined)\n    }\n\n    log(`Detaching user: ${userId}`)\n    // Delete triggers dispose callback which handles cleanup\n    this.cache.delete(userId)\n    return success(undefined)\n  }\n\n  /**\n   * Check if a user is currently attached\n   */\n  isAttached(userId: string): boolean {\n    return this.cache.has(userId)\n  }\n\n  /**\n   * Get statistics about a user's database\n   */\n  async getUserStats(userId: string): AsyncDuckPondResult<UserStats> {\n    const cached = this.cache.get(userId)\n\n    return success({\n      userId,\n      attached: cached.isSome(),\n      lastAccess: cached.fold(\n        () => new Date(0),\n        (u) => u.lastAccess,\n      ),\n      memoryUsage: cached.fold(\n        () => 0,\n        (u) => u.memoryUsage || 0,\n      ),\n      storageUsage: 0, // TODO: Calculate from R2\n      queryCount: 0, // TODO: Track queries\n    })\n  }\n\n  /**\n   * Get list of all currently cached users\n   * Returns a List of user IDs and cache statistics\n   */\n  listUsers(): ListUsersResult {\n    const stats = this.cache.getStats()\n    const keys = this.cache.keys()\n\n    return {\n      users: keys, // Already returns List<string>\n      count: stats.size,\n      maxActiveUsers: stats.maxSize,\n      utilizationPercent: stats.utilizationPercent,\n    }\n  }\n\n  /**\n   * Close DuckPond and cleanup all resources\n   */\n  close(): DuckPondResult<void> {\n    log(\"Closing DuckPond...\")\n\n    // Clear cache - triggers dispose callback for each user\n    this.cache.clear()\n\n    // Close instance\n    this.instance = Option.none()\n    this.initialized = false\n    log(\"DuckPond closed\")\n    return success(undefined)\n  }\n}\n"],"mappings":"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"}

package/dist/LRUCache-Bg_8n4IH.js

@@ -0,0 +1,2 @@
+import{loggers as e}from"./utils/logger.js";import{List as t}from"functype/list";import{Option as n}from"functype/option";import{LRUCache as r}from"lru-cache";function i(e){"@babel/helpers - typeof";return i=typeof Symbol==`function`&&typeof Symbol.iterator==`symbol`?function(e){return typeof e}:function(e){return e&&typeof Symbol==`function`&&e.constructor===Symbol&&e!==Symbol.prototype?`symbol`:typeof e},i(e)}function a(e,t){if(i(e)!=`object`||!e)return e;var n=e[Symbol.toPrimitive];if(n!==void 0){var r=n.call(e,t||`default`);if(i(r)!=`object`)return r;throw TypeError(`@@toPrimitive must return a primitive value.`)}return(t===`string`?String:Number)(e)}function o(e){var t=a(e,`string`);return i(t)==`symbol`?t:t+``}function s(e,t,n){return(t=o(t))in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}const c=e.cache;var l=class{constructor(e){s(this,`cache`,void 0),s(this,`maxSize`,void 0);let t=typeof e==`number`?{maxSize:e}:e;this.maxSize=t.maxSize,this.cache=new r({max:t.maxSize,ttl:t.ttl,updateAgeOnGet:!0,dispose:t.dispose?(e,n,r)=>{c(`Disposing ${n} (reason: ${r})`),t.dispose(e,n,r)}:void 0}),c(`Created LRU cache with maxSize=${t.maxSize}${t.ttl?`, ttl=${t.ttl}ms`:``}`)}get(e){let t=this.cache.get(e);return t===void 0?n.none():(t.lastAccess=new Date,c(`Cache hit: ${e}`),n(t))}set(e,t){t.lastAccess=new Date,this.cache.set(e,t),c(`Cache set: ${e} (size=${this.cache.size})`)}delete(e){let t=this.cache.delete(e);return t&&c(`Cache delete: ${e}`),t}has(e){return this.cache.has(e)}getLRU(){let e=this.cache.rkeys().next();return e.done||e.value===void 0?n.none():n(e.value)}getStale(e){let n=Date.now(),r=[];for(let t of this.cache.keys()){let i=this.cache.peek(t);i&&n-i.lastAccess.getTime()>e&&r.push(t)}return r.length>0&&c(`Found ${r.length} stale items`),t(r)}size(){return this.cache.size}clear(){let e=this.cache.size;this.cache.clear(),c(`Cache cleared (removed ${e} items)`)}values(){return t(Array.from(this.cache.values()))}keys(){return t(Array.from(this.cache.keys()))}purgeStale(){this.cache.purgeStale()}getStats(){let e=n(this.values().toArray().sort((e,t)=>e.lastAccess.getTime()-t.lastAccess.getTime())[0]).map(e=>e.lastAccess);return{size:this.cache.size,maxSize:this.maxSize,utilizationPercent:this.cache.size/this.maxSize*100,oldestAccessTime:e}}};export{s as n,l as t};
+//# sourceMappingURL=LRUCache-Bg_8n4IH.js.map

package/dist/LRUCache-Bg_8n4IH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LRUCache-Bg_8n4IH.js","names":["LRUCache","LRU","staleKeys: string[]"],"sources":["../src/cache/LRUCache.ts"],"sourcesContent":["import { List } from \"functype/list\"\nimport { Option } from \"functype/option\"\nimport { LRUCache as LRU } from \"lru-cache\"\n\nimport type { UserDatabase } from \"../types\"\nimport { loggers } from \"../utils/logger\"\n\nconst log = loggers.cache\n\n/**\n * Cache options for the LRU cache\n */\nexport interface LRUCacheOptions<T extends UserDatabase> {\n  /** Maximum number of items in cache */\n  maxSize: number\n  /** Time-to-live in milliseconds (optional, defaults to no TTL) */\n  ttl?: number\n  /** Callback when items are evicted/disposed */\n  dispose?: (value: T, key: string, reason: \"evict\" | \"set\" | \"delete\" | \"stale\") => void\n}\n\n/**\n * Functype-compatible LRU Cache wrapper\n *\n * Wraps the battle-tested lru-cache package with functype Option<T> and List<T>\n * for type-safe null handling and immutable collections.\n *\n * @example\n * ```typescript\n * const cache = new LRUCache<UserDatabase>({\n *   maxSize: 100,\n *   ttl: 1000 * 60 * 30, // 30 min\n *   dispose: (value, key, reason) => {\n *     console.log(`Evicting ${key}: ${reason}`)\n *   }\n * })\n *\n * cache.set(\"user1\", userDb)\n * const result = cache.get(\"user1\") // Option<UserDatabase>\n * result.fold(\n *   () => console.log(\"Not found\"),\n *   (db) => console.log(\"Found:\", db.userId)\n * )\n * ```\n */\nexport class LRUCache<T extends UserDatabase> {\n  private cache: LRU<string, T>\n  private readonly maxSize: number\n\n  constructor(options: number | LRUCacheOptions<T>) {\n    const opts = typeof options === \"number\" ? { maxSize: options } : options\n\n    this.maxSize = opts.maxSize\n\n    this.cache = new LRU<string, T>({\n      max: opts.maxSize,\n      ttl: opts.ttl,\n      updateAgeOnGet: true, // Reset TTL on access\n      dispose: opts.dispose\n        ? (value, key, reason) => {\n            log(`Disposing ${key} (reason: ${reason})`)\n            opts.dispose!(value, key, reason as \"evict\" | \"set\" | \"delete\" | \"stale\")\n          }\n        : undefined,\n    })\n\n    log(`Created LRU cache with maxSize=${opts.maxSize}${opts.ttl ? `, ttl=${opts.ttl}ms` : \"\"}`)\n  }\n\n  /**\n   * Get a value from the cache\n   * Returns Option.Some(value) if found, Option.None otherwise\n   */\n  get(key: string): Option<T> {\n    const value = this.cache.get(key)\n    if (value !== undefined) {\n      // Update lastAccess for stats tracking\n      value.lastAccess = new Date()\n      log(`Cache hit: ${key}`)\n      return Option(value)\n    }\n    return Option.none()\n  }\n\n  /**\n   * Set a value in the cache\n   * Automatically evicts LRU item if at capacity\n   */\n  set(key: string, value: T): void {\n    value.lastAccess = new Date()\n    this.cache.set(key, value)\n    log(`Cache set: ${key} (size=${this.cache.size})`)\n  }\n\n  /**\n   * Remove a value from the cache\n   */\n  delete(key: string): boolean {\n    const deleted = this.cache.delete(key)\n    if (deleted) {\n      log(`Cache delete: ${key}`)\n    }\n    return deleted\n  }\n\n  /**\n   * Check if a key exists in the cache (without updating recency)\n   */\n  has(key: string): boolean {\n    return this.cache.has(key)\n  }\n\n  /**\n   * Get the least recently used key\n   * Returns Option.Some(key) if cache not empty, Option.None otherwise\n   *\n   * Note: lru-cache maintains LRU order, so we iterate from oldest to newest\n   */\n  getLRU(): Option<string> {\n    // lru-cache keys() iterates from most recent to least recent by default\n    // Use rkeys() to get reverse (LRU first) order\n    const result = this.cache.rkeys().next()\n    if (result.done || result.value === undefined) {\n      return Option.none()\n    }\n    return Option(result.value)\n  }\n\n  /**\n   * Get all keys for items older than the timeout\n   * Returns a List of stale keys (functype immutable list)\n   *\n   * Note: If using TTL, stale items are automatically handled by the cache.\n   * This method is for manual staleness checks based on lastAccess.\n   */\n  getStale(timeoutMs: number): List<string> {\n    const now = Date.now()\n    const staleKeys: string[] = []\n\n    for (const key of this.cache.keys()) {\n      const value = this.cache.peek(key) // peek doesn't update recency\n      if (value && now - value.lastAccess.getTime() > timeoutMs) {\n        staleKeys.push(key)\n      }\n    }\n\n    if (staleKeys.length > 0) {\n      log(`Found ${staleKeys.length} stale items`)\n    }\n\n    return List(staleKeys)\n  }\n\n  /**\n   * Get the current size of the cache\n   */\n  size(): number {\n    return this.cache.size\n  }\n\n  /**\n   * Clear all items from the cache\n   * Note: This triggers dispose callbacks for each item\n   */\n  clear(): void {\n    const size = this.cache.size\n    this.cache.clear()\n    log(`Cache cleared (removed ${size} items)`)\n  }\n\n  /**\n   * Get all values as a List (functype immutable list)\n   */\n  values(): List<T> {\n    return List(Array.from(this.cache.values()))\n  }\n\n  /**\n   * Get all keys as a List\n   */\n  keys(): List<string> {\n    return List(Array.from(this.cache.keys()))\n  }\n\n  /**\n   * Purge stale items (TTL expired)\n   * Call this to force cleanup of expired items\n   */\n  purgeStale(): void {\n    this.cache.purgeStale()\n  }\n\n  /**\n   * Get cache statistics\n   */\n  getStats(): {\n    size: number\n    maxSize: number\n    utilizationPercent: number\n    oldestAccessTime: Option<Date>\n  } {\n    const values = this.values().toArray()\n    const sorted = values.sort((a, b) => a.lastAccess.getTime() - b.lastAccess.getTime())\n    const oldestAccessTime = Option(sorted[0]).map((item) => item.lastAccess)\n\n    return {\n      size: this.cache.size,\n      maxSize: this.maxSize,\n      utilizationPercent: (this.cache.size / this.maxSize) * 100,\n      oldestAccessTime,\n    }\n  }\n}\n"],"mappings":"m1BAOA,MAAM,EAAM,EAAQ,MAsCpB,IAAaA,EAAb,KAA8C,CAI5C,YAAY,EAAsC,QAH1C,QAAA,IAAA,GAAA,QACS,UAAA,IAAA,GAAA,CAGf,IAAM,EAAO,OAAO,GAAY,SAAW,CAAE,QAAS,EAAS,CAAG,EAElE,KAAK,QAAU,EAAK,QAEpB,KAAK,MAAQ,IAAIC,EAAe,CAC9B,IAAK,EAAK,QACV,IAAK,EAAK,IACV,eAAgB,GAChB,QAAS,EAAK,SACT,EAAO,EAAK,IAAW,CACtB,EAAI,aAAa,EAAI,YAAY,EAAO,GAAG,CAC3C,EAAK,QAAS,EAAO,EAAK,EAA+C,EAE3E,IAAA,GACL,CAAC,CAEF,EAAI,kCAAkC,EAAK,UAAU,EAAK,IAAM,SAAS,EAAK,IAAI,IAAM,KAAK,CAO/F,IAAI,EAAwB,CAC1B,IAAM,EAAQ,KAAK,MAAM,IAAI,EAAI,CAOjC,OANI,IAAU,IAAA,GAMP,EAAO,MAAM,EAJlB,EAAM,WAAa,IAAI,KACvB,EAAI,cAAc,IAAM,CACjB,EAAO,EAAM,EASxB,IAAI,EAAa,EAAgB,CAC/B,EAAM,WAAa,IAAI,KACvB,KAAK,MAAM,IAAI,EAAK,EAAM,CAC1B,EAAI,cAAc,EAAI,SAAS,KAAK,MAAM,KAAK,GAAG,CAMpD,OAAO,EAAsB,CAC3B,IAAM,EAAU,KAAK,MAAM,OAAO,EAAI,CAItC,OAHI,GACF,EAAI,iBAAiB,IAAM,CAEtB,EAMT,IAAI,EAAsB,CACxB,OAAO,KAAK,MAAM,IAAI,EAAI,CAS5B,QAAyB,CAGvB,IAAM,EAAS,KAAK,MAAM,OAAO,CAAC,MAAM,CAIxC,OAHI,EAAO,MAAQ,EAAO,QAAU,IAAA,GAC3B,EAAO,MAAM,CAEf,EAAO,EAAO,MAAM,CAU7B,SAAS,EAAiC,CACxC,IAAM,EAAM,KAAK,KAAK,CAChBC,EAAsB,EAAE,CAE9B,IAAK,IAAM,KAAO,KAAK,MAAM,MAAM,CAAE,CACnC,IAAM,EAAQ,KAAK,MAAM,KAAK,EAAI,CAC9B,GAAS,EAAM,EAAM,WAAW,SAAS,CAAG,GAC9C,EAAU,KAAK,EAAI,CAQvB,OAJI,EAAU,OAAS,GACrB,EAAI,SAAS,EAAU,OAAO,cAAc,CAGvC,EAAK,EAAU,CAMxB,MAAe,CACb,OAAO,KAAK,MAAM,KAOpB,OAAc,CACZ,IAAM,EAAO,KAAK,MAAM,KACxB,KAAK,MAAM,OAAO,CAClB,EAAI,0BAA0B,EAAK,SAAS,CAM9C,QAAkB,CAChB,OAAO,EAAK,MAAM,KAAK,KAAK,MAAM,QAAQ,CAAC,CAAC,CAM9C,MAAqB,CACnB,OAAO,EAAK,MAAM,KAAK,KAAK,MAAM,MAAM,CAAC,CAAC,CAO5C,YAAmB,CACjB,KAAK,MAAM,YAAY,CAMzB,UAKE,CAGA,IAAM,EAAmB,EAFV,KAAK,QAAQ,CAAC,SAAS,CAChB,MAAM,EAAG,IAAM,EAAE,WAAW,SAAS,CAAG,EAAE,WAAW,SAAS,CAAC,CAC9C,GAAG,CAAC,IAAK,GAAS,EAAK,WAAW,CAEzE,MAAO,CACL,KAAM,KAAK,MAAM,KACjB,QAAS,KAAK,QACd,mBAAqB,KAAK,MAAM,KAAO,KAAK,QAAW,IACvD,mBACD"}

package/dist/cache/LRUCache.d.ts

@@ -1,75 +1,113 @@
-import { List } from 'functype/list';
-import { Option } from 'functype/option';
-import { UserDatabase } from '../types.js';
-import '@duckdb/node-api';
-import 'functype/either';
+import { UserDatabase } from "../types.js";
+import { List } from "functype/list";
+import { Option } from "functype/option";
 
+//#region src/cache/LRUCache.d.ts
+
+/**
+ * Cache options for the LRU cache
+ */
+interface LRUCacheOptions<T extends UserDatabase> {
+  /** Maximum number of items in cache */
+  maxSize: number;
+  /** Time-to-live in milliseconds (optional, defaults to no TTL) */
+  ttl?: number;
+  /** Callback when items are evicted/disposed */
+  dispose?: (value: T, key: string, reason: "evict" | "set" | "delete" | "stale") => void;
+}
 /**
- * LRU Cache for managing active user database connections
+ * Functype-compatible LRU Cache wrapper
  *
- * Uses functype Option for safe null handling
+ * Wraps the battle-tested lru-cache package with functype Option<T> and List<T>
+ * for type-safe null handling and immutable collections.
+ *
+ * @example
+ * ```typescript
+ * const cache = new LRUCache<UserDatabase>({
+ *   maxSize: 100,
+ *   ttl: 1000 * 60 * 30, // 30 min
+ *   dispose: (value, key, reason) => {
+ *     console.log(`Evicting ${key}: ${reason}`)
+ *   }
+ * })
+ *
+ * cache.set("user1", userDb)
+ * const result = cache.get("user1") // Option<UserDatabase>
+ * result.fold(
+ *   () => console.log("Not found"),
+ *   (db) => console.log("Found:", db.userId)
+ * )
+ * ```
  */
 declare class LRUCache<T extends UserDatabase> {
-    private cache;
-    private readonly maxSize;
-    constructor(maxSize?: number);
-    /**
-     * Get a value from the cache
-     * Returns Option.Some(value) if found, Option.None otherwise
-     */
-    get(key: string): Option<T>;
-    /**
-     * Set a value in the cache
-     * Evicts LRU item if at capacity
-     */
-    set(key: string, value: T): void;
-    /**
-     * Remove a value from the cache
-     */
-    delete(key: string): boolean;
-    /**
-     * Check if a key exists in the cache
-     */
-    has(key: string): boolean;
-    /**
-     * Get the least recently used key
-     * Returns Option.Some(key) if cache not empty, Option.None otherwise
-     */
-    getLRU(): Option<string>;
-    /**
-     * Evict the least recently used item
-     */
-    private evictLRU;
-    /**
-     * Get all keys for items older than the timeout
-     * Returns a List of stale keys (functype immutable list)
-     */
-    getStale(timeoutMs: number): List<string>;
-    /**
-     * Get the current size of the cache
-     */
-    size(): number;
-    /**
-     * Clear all items from the cache
-     */
-    clear(): void;
-    /**
-     * Get all values as a List (functype immutable list)
-     */
-    values(): List<T>;
-    /**
-     * Get all keys as a List
-     */
-    keys(): List<string>;
-    /**
-     * Get cache statistics
-     */
-    getStats(): {
-        size: number;
-        maxSize: number;
-        utilizationPercent: number;
-        oldestAccessTime: Option<Date>;
-    };
+  private cache;
+  private readonly maxSize;
+  constructor(options: number | LRUCacheOptions<T>);
+  /**
+   * Get a value from the cache
+   * Returns Option.Some(value) if found, Option.None otherwise
+   */
+  get(key: string): Option<T>;
+  /**
+   * Set a value in the cache
+   * Automatically evicts LRU item if at capacity
+   */
+  set(key: string, value: T): void;
+  /**
+   * Remove a value from the cache
+   */
+  delete(key: string): boolean;
+  /**
+   * Check if a key exists in the cache (without updating recency)
+   */
+  has(key: string): boolean;
+  /**
+   * Get the least recently used key
+   * Returns Option.Some(key) if cache not empty, Option.None otherwise
+   *
+   * Note: lru-cache maintains LRU order, so we iterate from oldest to newest
+   */
+  getLRU(): Option<string>;
+  /**
+   * Get all keys for items older than the timeout
+   * Returns a List of stale keys (functype immutable list)
+   *
+   * Note: If using TTL, stale items are automatically handled by the cache.
+   * This method is for manual staleness checks based on lastAccess.
+   */
+  getStale(timeoutMs: number): List<string>;
+  /**
+   * Get the current size of the cache
+   */
+  size(): number;
+  /**
+   * Clear all items from the cache
+   * Note: This triggers dispose callbacks for each item
+   */
+  clear(): void;
+  /**
+   * Get all values as a List (functype immutable list)
+   */
+  values(): List<T>;
+  /**
+   * Get all keys as a List
+   */
+  keys(): List<string>;
+  /**
+   * Purge stale items (TTL expired)
+   * Call this to force cleanup of expired items
+   */
+  purgeStale(): void;
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    maxSize: number;
+    utilizationPercent: number;
+    oldestAccessTime: Option<Date>;
+  };
 }
-
-export { LRUCache };
+//#endregion
+export { LRUCache, LRUCacheOptions };
+//# sourceMappingURL=LRUCache.d.ts.map

package/dist/cache/LRUCache.js

@@ -1,2 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkJ2OQ62DVjs = require('../chunk-J2OQ62DV.js');require('../chunk-Q6UFPTQC.js');require('../chunk-5XGN7UAV.js');exports.LRUCache = _chunkJ2OQ62DVjs.a;
-//# sourceMappingURL=LRUCache.js.map
+import"../utils/logger.js";import{t as e}from"../LRUCache-Bg_8n4IH.js";export{e as LRUCache};

package/dist/index.d.ts

@@ -1,12 +1,10 @@
-export { DuckPond } from './DuckPond.js';
-export { AsyncDuckPondResult, ColumnSchema, CreateUserOptions, DuckPondConfig, DuckPondError, DuckPondEvent, DuckPondMetrics, DuckPondResult, ErrorCode, FileInfo, ListUsersResult, QueryResult, ResolvedConfig, Schema, StorageStats, TableSchema, UserDatabase, UserStats } from './types.js';
-export { Errors, createError, formatError, success, toDuckPondError } from './utils/errors.js';
-export { createLogger, loggers } from './utils/logger.js';
-export { LRUCache } from './cache/LRUCache.js';
-export { Either, Left, Right } from 'functype/either';
-export { List } from 'functype/list';
-export { Option } from 'functype/option';
-export { Try } from 'functype/try';
-import '@duckdb/node-api';
-import 'functype';
-import 'debug';
+import { AsyncDuckPondResult, ColumnSchema, CreateUserOptions, DuckPondConfig, DuckPondError, DuckPondEvent, DuckPondMetrics, DuckPondResult, ErrorCode, FileInfo, ListUsersResult, QueryResult, ResolvedConfig, Schema, StorageStats, TableSchema, UserDatabase, UserStats } from "./types.js";
+import { DuckPond } from "./DuckPond.js";
+import { LRUCache, LRUCacheOptions } from "./cache/LRUCache.js";
+import { Errors, createError, formatError, success, toDuckPondError } from "./utils/errors.js";
+import { createLogger, loggers } from "./utils/logger.js";
+import { List } from "functype/list";
+import { Option } from "functype/option";
+import { Either, Left, Right } from "functype/either";
+import { Try } from "functype/try";
+export { type AsyncDuckPondResult, type ColumnSchema, type CreateUserOptions, DuckPond, type DuckPondConfig, type DuckPondError, type DuckPondEvent, type DuckPondMetrics, type DuckPondResult, Either, ErrorCode, Errors, type FileInfo, LRUCache, type LRUCacheOptions, Left, List, type ListUsersResult, Option, type QueryResult, type ResolvedConfig, Right, type Schema, type StorageStats, type TableSchema, Try, type UserDatabase, type UserStats, createError, createLogger, formatError, loggers, success, toDuckPondError };

package/dist/index.js

@@ -1,2 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkMLZHFU2Bjs = require('./chunk-MLZHFU2B.js');var _chunkJ2OQ62DVjs = require('./chunk-J2OQ62DV.js');var _chunkMZTKR3LRjs = require('./chunk-MZTKR3LR.js');var _chunk2PPSIE57js = require('./chunk-2PPSIE57.js');var _chunkQ6UFPTQCjs = require('./chunk-Q6UFPTQC.js');require('./chunk-5XGN7UAV.js');var _either = require('functype/either');var _list = require('functype/list');var _option = require('functype/option');var _try = require('functype/try');exports.DuckPond = _chunkMLZHFU2Bjs.a; exports.Either = _either.Either; exports.ErrorCode = _chunk2PPSIE57js.a; exports.Errors = _chunkMZTKR3LRjs.d; exports.LRUCache = _chunkJ2OQ62DVjs.a; exports.Left = _either.Left; exports.List = _list.List; exports.Option = _option.Option; exports.Right = _either.Right; exports.Try = _try.Try; exports.createError = _chunkMZTKR3LRjs.a; exports.createLogger = _chunkQ6UFPTQCjs.a; exports.formatError = _chunkMZTKR3LRjs.e; exports.loggers = _chunkQ6UFPTQCjs.b; exports.success = _chunkMZTKR3LRjs.b; exports.toDuckPondError = _chunkMZTKR3LRjs.c;
-//# sourceMappingURL=index.js.map
+import{createLogger as e,loggers as t}from"./utils/logger.js";import{t as n}from"./LRUCache-Bg_8n4IH.js";import{ErrorCode as r}from"./types.js";import{Errors as i,createError as a,formatError as o,success as s,toDuckPondError as c}from"./utils/errors.js";import{DuckPond as l}from"./DuckPond.js";import{List as u}from"functype/list";import{Option as d}from"functype/option";import{Either as f,Left as p,Right as m}from"functype/either";import{Try as h}from"functype/try";export{l as DuckPond,f as Either,r as ErrorCode,i as Errors,n as LRUCache,p as Left,u as List,d as Option,m as Right,h as Try,a as createError,e as createLogger,o as formatError,t as loggers,s as success,c as toDuckPondError};