@lakutata/cache 3.0.0-beta.0

package/dist/types/cache/stores/MemcacheStore.d.ts

@@ -0,0 +1,42 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { MemcacheCacheOptions } from '../options/MemcacheCacheOptions.js';
+interface MemcacheClient {
+    get(key: string): Promise<{
+        value: Buffer | null;
+    }>;
+    set(key: string, value: string, options: {
+        expires?: number;
+    }): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    flush(): Promise<unknown>;
+    close(): void;
+}
+/**
+ * The Memcache store
+ * Key format: "{namespace}:{namespace}:{key}", or "{key}" without namespace
+ */
+export declare class MemcacheStore extends SerializedCacheStore {
+    protected readonly options: MemcacheCacheOptions;
+    protected client: MemcacheClient;
+    constructor(options: MemcacheCacheOptions);
+    protected storeKey(key: string): string;
+    /**
+     * The memcached expiration of an entry, the entries expire after their expiration time
+     * @param entry
+     * @protected
+     */
+    protected expiration(entry: SerializedEntry): number;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    /**
+     * Memcached cannot list the keys, all the entries are flushed
+     */
+    clear(): Promise<void>;
+}
+export {};

package/dist/types/cache/stores/MemoryStore.d.ts

@@ -0,0 +1,34 @@
+import { CacheStore, CacheStoreSetEntry } from './CacheStore.js';
+import { CacheEntry } from '../lib/Serializer.js';
+/**
+ * The in-memory store, the values are kept by reference
+ */
+export declare class MemoryStore extends CacheStore {
+    protected readonly sweepInterval: number;
+    protected readonly entries: Map<string, CacheEntry>;
+    protected sweeper?: NodeJS.Timeout;
+    /**
+     * @param sweepInterval ms, remove the expired entries in each interval
+     */
+    constructor(sweepInterval?: number);
+    /**
+     * Remove the expired entries
+     * @protected
+     */
+    protected sweep(): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Read an entry, the expired entries are removed
+     * @param key
+     * @protected
+     */
+    protected read(key: string): CacheEntry | undefined;
+    get(key: string): Promise<CacheEntry | undefined>;
+    getMany(keys: string[]): Promise<(CacheEntry | undefined)[]>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    setMany(entries: CacheStoreSetEntry[]): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}

package/dist/types/cache/stores/MongoStore.d.ts

@@ -0,0 +1,55 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { MongoCacheOptions } from '../options/MongoCacheOptions.js';
+type MongoDocument = {
+    key: string;
+    value: string;
+    expiresAt?: Date | null;
+};
+interface MongoCollection {
+    createIndex(keys: Record<string, number>, options: Record<string, unknown>): Promise<unknown>;
+    findOne(filter: Record<string, unknown>, options?: Record<string, unknown>): Promise<MongoDocument | null>;
+    find(filter: Record<string, unknown>, options?: Record<string, unknown>): {
+        toArray(): Promise<MongoDocument[]>;
+    };
+    updateOne(filter: Record<string, unknown>, update: Record<string, unknown>, options: Record<string, unknown>): Promise<unknown>;
+    bulkWrite(operations: Record<string, unknown>[], options: Record<string, unknown>): Promise<unknown>;
+    deleteOne(filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+    deleteMany(filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+}
+interface MongoClient {
+    connect(): Promise<unknown>;
+    close(): Promise<void>;
+    db(name: string): {
+        collection(name: string): MongoCollection;
+    };
+}
+/**
+ * The MongoDB store
+ * Document format: {key: "{namespace}:{key}", value: serialized entry, expiresAt: Date | null}, removed by a TTL index
+ */
+export declare class MongoStore extends SerializedCacheStore {
+    protected readonly options: MongoCacheOptions;
+    protected client: MongoClient;
+    protected collection: MongoCollection;
+    constructor(options: MongoCacheOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    /**
+     * The upsert of an entry
+     * @param entry
+     * @protected
+     */
+    protected update(entry: SerializedEntry): [Record<string, unknown>, Record<string, unknown>];
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export {};

package/dist/types/cache/stores/MysqlStore.d.ts

@@ -0,0 +1,27 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { MysqlCacheOptions } from '../options/MysqlCacheOptions.js';
+interface MysqlPool {
+    query(sql: string, values?: unknown[]): Promise<[any, unknown]>;
+    escapeId(identifier: string): string;
+    end(): Promise<void>;
+}
+/**
+ * The MySQL store
+ * Table format: (id VARCHAR(255) PRIMARY KEY, value TEXT), with "{namespace}:{key}" ids
+ */
+export declare class MysqlStore extends SerializedCacheStore {
+    protected readonly options: MysqlCacheOptions;
+    protected pool: MysqlPool;
+    protected table: string;
+    constructor(options: MysqlCacheOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export {};

package/dist/types/cache/stores/PostgresStore.d.ts

@@ -0,0 +1,30 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { PostgresCacheOptions } from '../options/PostgresCacheOptions.js';
+interface PostgresPool {
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    end(): Promise<void>;
+}
+/**
+ * The PostgreSQL store
+ * Table format: (key VARCHAR(255) PRIMARY KEY, value TEXT), with "{namespace}:{key}" keys
+ */
+export declare class PostgresStore extends SerializedCacheStore {
+    protected readonly options: PostgresCacheOptions;
+    protected pool: PostgresPool;
+    protected table: string;
+    constructor(options: PostgresCacheOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export {};

package/dist/types/cache/stores/RedisStore.d.ts

@@ -0,0 +1,58 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { RedisCacheOptions } from '../options/RedisCacheOptions.js';
+interface RedisCommands<R> {
+    set(key: string, value: string): R;
+    pSetEx(key: string, milliseconds: number, value: string): R;
+}
+interface RedisMulti extends RedisCommands<RedisMulti> {
+    exec(): Promise<unknown[]>;
+}
+interface RedisClient extends RedisCommands<Promise<unknown>> {
+    isOpen: boolean;
+    isReady: boolean;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    connect(): Promise<unknown>;
+    disconnect(): Promise<unknown>;
+    quit?(): Promise<unknown>;
+    close?(): Promise<unknown>;
+    destroy?(): void;
+    get(key: string): Promise<string | null>;
+    mGet(keys: string[]): Promise<(string | null)[]>;
+    del(keys: string | string[]): Promise<number>;
+    unlink(keys: string | string[]): Promise<number>;
+    flushDb(): Promise<unknown>;
+    multi(): RedisMulti;
+    scanIterator(options: {
+        MATCH?: string;
+        COUNT?: number;
+        TYPE?: string;
+    }): AsyncIterable<string | string[]>;
+}
+/**
+ * The Redis store
+ * Key format: "{namespace}{keyPrefixSeparator}{namespace}:{key}", or "{key}" without namespace
+ */
+export declare class RedisStore extends SerializedCacheStore {
+    protected readonly options: RedisCacheOptions;
+    protected readonly separator: string;
+    protected readonly clearBatchSize: number;
+    protected client: RedisClient;
+    constructor(options: RedisCacheOptions);
+    protected storeKey(key: string): string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    /**
+     * Delete keys
+     * @param keys
+     * @protected
+     */
+    protected unlink(keys: string | string[]): Promise<number>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export {};

package/dist/types/cache/stores/SerializedCacheStore.d.ts

@@ -0,0 +1,48 @@
+import { CacheStore, CacheStoreSetEntry } from './CacheStore.js';
+import { CacheEntry } from '../lib/Serializer.js';
+export type SerializedEntry = {
+    key: string;
+    data: string;
+    ttl?: number;
+    expires?: number;
+};
+/**
+ * A store keeping the entries serialized, under namespaced keys
+ */
+export declare abstract class SerializedCacheStore extends CacheStore {
+    protected readonly namespace?: string;
+    protected constructor(namespace?: string);
+    /**
+     * The key of an entry in the backend
+     * @param key
+     * @protected
+     */
+    protected storeKey(key: string): string;
+    protected abstract read(key: string): Promise<string | undefined>;
+    protected abstract readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected abstract write(entry: SerializedEntry): Promise<void>;
+    protected abstract writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected abstract remove(key: string): Promise<boolean>;
+    protected abstract removeMany(keys: string[]): Promise<boolean>;
+    /**
+     * Parse an entry read from the backend, the expired entries are removed
+     * @param storeKey
+     * @param data
+     * @protected
+     */
+    protected parse(storeKey: string, data: string | undefined): CacheEntry | undefined;
+    /**
+     * Serialize an entry
+     * @param key
+     * @param value
+     * @param ttl
+     * @protected
+     */
+    protected serialize(key: string, value: unknown, ttl?: number): SerializedEntry;
+    get(key: string): Promise<CacheEntry | undefined>;
+    getMany(keys: string[]): Promise<(CacheEntry | undefined)[]>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    setMany(entries: CacheStoreSetEntry[]): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    deleteMany(keys: string[]): Promise<boolean>;
+}

package/dist/types/cache/stores/SqliteStore.d.ts

@@ -0,0 +1,44 @@
+import { SerializedCacheStore, SerializedEntry } from './SerializedCacheStore.js';
+import { SqliteCacheOptions } from '../options/SqliteCacheOptions.js';
+interface SqliteDatabase {
+    configure(option: 'busyTimeout', value: number): void;
+    all(sql: string, params: unknown[], callback: (error: Error | null, rows: any[]) => void): void;
+    run(sql: string, params: unknown[], callback: (this: {
+        changes: number;
+    }, error: Error | null) => void): void;
+    close(callback: (error: Error | null) => void): void;
+}
+/**
+ * The SQLite store
+ * Table format: (key VARCHAR(255) PRIMARY KEY, value TEXT), with "{namespace}:{key}" keys
+ */
+export declare class SqliteStore extends SerializedCacheStore {
+    protected readonly options: SqliteCacheOptions;
+    protected database: SqliteDatabase;
+    protected readonly table: string;
+    constructor(options: SqliteCacheOptions);
+    /**
+     * Query the rows
+     * @param sql
+     * @param params
+     * @protected
+     */
+    protected all(sql: string, params: unknown[]): Promise<any[]>;
+    /**
+     * Run a statement, resolve the number of changed rows
+     * @param sql
+     * @param params
+     * @protected
+     */
+    protected run(sql: string, params?: unknown[]): Promise<number>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    protected read(key: string): Promise<string | undefined>;
+    protected readMany(keys: string[]): Promise<(string | undefined)[]>;
+    protected write(entry: SerializedEntry): Promise<void>;
+    protected writeMany(entries: SerializedEntry[]): Promise<void>;
+    protected remove(key: string): Promise<boolean>;
+    protected removeMany(keys: string[]): Promise<boolean>;
+    clear(): Promise<void>;
+}
+export {};

package/dist/types/cache/types/CacheStoreOptions.d.ts

@@ -0,0 +1,15 @@
+import { FileCacheOptions } from '../options/FileCacheOptions.js';
+import { MemoryCacheOptions } from '../options/MemoryCacheOptions.js';
+import { RedisCacheOptions } from '../options/RedisCacheOptions.js';
+import { SqliteCacheOptions } from '../options/SqliteCacheOptions.js';
+import { PostgresCacheOptions } from '../options/PostgresCacheOptions.js';
+import { MysqlCacheOptions } from '../options/MysqlCacheOptions.js';
+import { MongoCacheOptions } from '../options/MongoCacheOptions.js';
+import { MemcacheCacheOptions } from '../options/MemcacheCacheOptions.js';
+/**
+ * The options of one store of a `Cacher`, told apart by their `type`: `'memory'` ({@link MemoryCacheOptions}, the
+ * store of a cache without stores), `'file'` ({@link FileCacheOptions}), `'redis'` ({@link RedisCacheOptions}),
+ * `'memcache'` ({@link MemcacheCacheOptions}), `'mongo'` ({@link MongoCacheOptions}), `'sqlite'`
+ * ({@link SqliteCacheOptions}), `'postgres'` ({@link PostgresCacheOptions}) or `'mysql'` ({@link MysqlCacheOptions}).
+ */
+export type CacheStoreOptions = MemoryCacheOptions | FileCacheOptions | RedisCacheOptions | MemcacheCacheOptions | MongoCacheOptions | SqliteCacheOptions | PostgresCacheOptions | MysqlCacheOptions;

package/dist/types/exports/Cache.d.ts

@@ -0,0 +1,12 @@
+export * from '../cache/Cacher.js';
+export * from '../cache/interfaces/CacherOptions.js';
+export * from '../cache/options/FileCacheOptions.js';
+export * from '../cache/options/MemoryCacheOptions.js';
+export * from '../cache/options/MemcacheCacheOptions.js';
+export * from '../cache/options/MongoCacheOptions.js';
+export * from '../cache/options/MysqlCacheOptions.js';
+export * from '../cache/options/PostgresCacheOptions.js';
+export * from '../cache/options/RedisCacheOptions.js';
+export * from '../cache/options/SqliteCacheOptions.js';
+export * from '../cache/types/CacheStoreOptions.js';
+export * from '../cache/exceptions/CacheDriverNotFoundException.js';

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@lakutata/cache",
+  "version": "3.0.0-beta.0",
+  "description": "The cache component of the lakutata framework (memory, file, Redis, Memcache, MongoDB, SQLite, PostgreSQL, MySQL stores).",
+  "type": "module",
+  "main": "./dist/cjs/exports/Cache.js",
+  "types": "./dist/cjs/exports/Cache.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/Cache.d.ts",
+        "default": "./dist/esm/exports/Cache.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Cache.d.ts",
+        "default": "./dist/cjs/exports/Cache.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test \"dist/esm/tests/*.spec.js\"",
+    "test:stores": "npm run compile && CACHE_TEST_STORES=1 node --test --test-concurrency=1 \"dist/esm/tests/stores/*.spec.js\""
+  },
+  "peerDependencies": {
+    "@lakutata/core": "3.0.0-beta.0",
+    "@lakutata/utils": "3.0.0-beta.0",
+    "memjs": "^1.3.2",
+    "mongodb": ">=6.0.0",
+    "mysql2": "^3.0.0",
+    "pg": "^8.0.0",
+    "redis": "^4.6.0 || ^5.0.0",
+    "sqlite3": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "memjs": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json"
+  ]
+}