@geekmidas/cache 10.0.0-alpha.99 → 10.0.0

package/src/upstash.ts

@@ -0,0 +1,41 @@
+import { Redis } from '@upstash/redis';
+import type { Cache } from './';
+
+export class UpstashCache implements Cache {
+	private client: Redis;
+
+	constructor(url: string, token: string) {
+		this.client = new Redis({
+			url,
+			token,
+		});
+	}
+
+	async ttl(key: string): Promise<number> {
+		const ttl = await this.client.ttl(key);
+
+		if (ttl === -2) {
+			return 0; // Key does not exist
+		}
+
+		return ttl; // Returns TTL in seconds
+	}
+
+	async get<T>(key: string): Promise<T | undefined> {
+		const v = await this.client.get(key);
+
+		if (v === null) {
+			return undefined;
+		}
+
+		return v as T;
+	}
+
+	async set<T>(key: string, value: T, ttl = 3600): Promise<void> {
+		await this.client.set(key, value, { ex: ttl });
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.client.del(key);
+	}
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"]
+}

package/tsdown.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+	external: ['expo-secure-store', '@upstash/redis'],
+});

package/dist/index-BbdGhmWP.d.cts

@@ -1,62 +0,0 @@
-//#region src/registry.d.ts
-/** What a driver has to supply: a scheme it answers to, and a client for a URL. */
-interface CacheDriver {
-  /** Including the colon, as `URL.protocol` reports it — `redis:`, `https:`. */
-  scheme: string;
-  create(url: string): Cache;
-}
-/** Make a driver available to {@link createCacheClient}. Idempotent. */
-declare function registerCacheDriver(driver: CacheDriver): void;
-/** Which schemes are currently registered — the useful half of a failure. */
-declare function registeredCacheSchemes(): string[];
-/**
- * Build a client for a URL.
- *
- * @throws {UnregisteredCacheScheme} when no driver handles the scheme, which in
- * practice means the entry point registered a different one — the backend and
- * the build disagreeing, caught at the first cache call rather than never.
- */
-declare function createCacheClient(url: string): Cache;
-/** No driver handles the scheme in a cache URL. */
-declare class UnregisteredCacheScheme extends Error {
-  readonly url: string;
-  readonly scheme: string;
-  readonly registered: readonly string[];
-  constructor(url: string, scheme: string, registered: readonly string[]);
-}
-//#endregion
-//#region src/index.d.ts
-declare const getExpirationInSeconds: (expiresAt: string | number | Date | undefined | null) => number;
-interface Cache {
-  /**
-   * Retrieves a value from the cache.
-   *
-   * @param key The key to retrieve the value for.
-   * @returns The cached value, or undefined if not found.
-   */
-  get<T>(key: string): Promise<T | undefined>;
-  /**
-   * Sets a value in the cache.
-   *
-   * @param key The key to set the value for.
-   * @param value The value to cache.
-   * @param ttl Optional time-to-live in seconds. If not provided, the value will not expire.
-   */
-  set<T>(key: string, value: T, ttl?: number): Promise<void>;
-  /**
-   * Deletes a value from the cache.
-   *
-   * @param key The key to delete from the cache.
-   */
-  delete(key: string): Promise<void>;
-  /**
-   * Retrieves the time-to-live (TTL) for a cached value.
-   *
-   * @param key The key to retrieve the TTL for.
-   * @returns The TTL in seconds, or 0 if the key does not exist.
-   */
-  ttl(key: string): Promise<number>;
-}
-//#endregion
-export { createCacheClient as a, UnregisteredCacheScheme as i, getExpirationInSeconds as n, registerCacheDriver as o, CacheDriver as r, registeredCacheSchemes as s, Cache as t };
-//# sourceMappingURL=index-BbdGhmWP.d.cts.map

package/dist/index-BbdGhmWP.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-BbdGhmWP.d.cts","names":[],"sources":["../src/registry.ts","../src/index.ts"],"mappings":";;UAgBiB;;EAEhB;EACA,OAAO,cAAc;;;iBAMN,oBAAoB,QAAQ;;iBAK5B;;;;;;;;iBAWA,kBAAkB,cAAc;;cAYnC,gCAAgC;WAElC;WACA;WACA;EAHV,YACU,aACA,gBACA;;;;cCvDE,yBAAsB,6BACL;UAcb;;;;;;;EAOhB,IAAI,GAAG,cAAc,QAAQ;;;;;;;;EAQ7B,IAAI,GAAG,aAAa,OAAO,GAAG,eAAe;;;;;;EAM7C,OAAO,cAAc;;;;;;;EAQrB,IAAI,cAAc"}

package/dist/index-BbdGhmWP.d.mts

@@ -1,62 +0,0 @@
-//#region src/registry.d.ts
-/** What a driver has to supply: a scheme it answers to, and a client for a URL. */
-interface CacheDriver {
-  /** Including the colon, as `URL.protocol` reports it — `redis:`, `https:`. */
-  scheme: string;
-  create(url: string): Cache;
-}
-/** Make a driver available to {@link createCacheClient}. Idempotent. */
-declare function registerCacheDriver(driver: CacheDriver): void;
-/** Which schemes are currently registered — the useful half of a failure. */
-declare function registeredCacheSchemes(): string[];
-/**
- * Build a client for a URL.
- *
- * @throws {UnregisteredCacheScheme} when no driver handles the scheme, which in
- * practice means the entry point registered a different one — the backend and
- * the build disagreeing, caught at the first cache call rather than never.
- */
-declare function createCacheClient(url: string): Cache;
-/** No driver handles the scheme in a cache URL. */
-declare class UnregisteredCacheScheme extends Error {
-  readonly url: string;
-  readonly scheme: string;
-  readonly registered: readonly string[];
-  constructor(url: string, scheme: string, registered: readonly string[]);
-}
-//#endregion
-//#region src/index.d.ts
-declare const getExpirationInSeconds: (expiresAt: string | number | Date | undefined | null) => number;
-interface Cache {
-  /**
-   * Retrieves a value from the cache.
-   *
-   * @param key The key to retrieve the value for.
-   * @returns The cached value, or undefined if not found.
-   */
-  get<T>(key: string): Promise<T | undefined>;
-  /**
-   * Sets a value in the cache.
-   *
-   * @param key The key to set the value for.
-   * @param value The value to cache.
-   * @param ttl Optional time-to-live in seconds. If not provided, the value will not expire.
-   */
-  set<T>(key: string, value: T, ttl?: number): Promise<void>;
-  /**
-   * Deletes a value from the cache.
-   *
-   * @param key The key to delete from the cache.
-   */
-  delete(key: string): Promise<void>;
-  /**
-   * Retrieves the time-to-live (TTL) for a cached value.
-   *
-   * @param key The key to retrieve the TTL for.
-   * @returns The TTL in seconds, or 0 if the key does not exist.
-   */
-  ttl(key: string): Promise<number>;
-}
-//#endregion
-export { createCacheClient as a, UnregisteredCacheScheme as i, getExpirationInSeconds as n, registerCacheDriver as o, CacheDriver as r, registeredCacheSchemes as s, Cache as t };
-//# sourceMappingURL=index-BbdGhmWP.d.mts.map

package/dist/index-BbdGhmWP.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-BbdGhmWP.d.mts","names":[],"sources":["../src/registry.ts","../src/index.ts"],"mappings":";;UAgBiB;;EAEhB;EACA,OAAO,cAAc;;;iBAMN,oBAAoB,QAAQ;;iBAK5B;;;;;;;;iBAWA,kBAAkB,cAAc;;cAYnC,gCAAgC;WAElC;WACA;WACA;EAHV,YACU,aACA,gBACA;;;;cCvDE,yBAAsB,6BACL;UAcb;;;;;;;EAOhB,IAAI,GAAG,cAAc,QAAQ;;;;;;;;EAQ7B,IAAI,GAAG,aAAa,OAAO,GAAG,eAAe;;;;;;EAM7C,OAAO,cAAc;;;;;;;EAQrB,IAAI,cAAc"}

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.cjs","names":["differenceInSeconds"],"sources":["../src/index.ts"],"sourcesContent":["import { differenceInSeconds } from 'date-fns';\n\nexport const getExpirationInSeconds = (\n\texpiresAt: string | number | Date | undefined | null,\n): number => {\n\tif (!expiresAt) {\n\t\treturn 0;\n\t}\n\n\tconst expirationDate = new Date(expiresAt);\n\tconst now = new Date();\n\n\tconst secondsLeft = differenceInSeconds(expirationDate, now);\n\n\treturn Math.max(secondsLeft, 0);\n};\n\nexport interface Cache {\n\t/**\n\t * Retrieves a value from the cache.\n\t *\n\t * @param key The key to retrieve the value for.\n\t * @returns The cached value, or undefined if not found.\n\t */\n\tget<T>(key: string): Promise<T | undefined>;\n\t/**\n\t * Sets a value in the cache.\n\t *\n\t * @param key The key to set the value for.\n\t * @param value The value to cache.\n\t * @param ttl Optional time-to-live in seconds. If not provided, the value will not expire.\n\t */\n\tset<T>(key: string, value: T, ttl?: number): Promise<void>;\n\t/**\n\t * Deletes a value from the cache.\n\t *\n\t * @param key The key to delete from the cache.\n\t */\n\tdelete(key: string): Promise<void>;\n\n\t/**\n\t * Retrieves the time-to-live (TTL) for a cached value.\n\t *\n\t * @param key The key to retrieve the TTL for.\n\t * @returns The TTL in seconds, or 0 if the key does not exist.\n\t */\n\tttl(key: string): Promise<number>;\n}\n\nexport type { CacheDriver } from './registry';\nexport {\n\tcreateCacheClient,\n\tregisterCacheDriver,\n\tregisteredCacheSchemes,\n\tUnregisteredCacheScheme,\n} from './registry';\n"],"mappings":";;;;AAEA,MAAa,0BACZ,cACY;CACZ,IAAI,CAAC,WACJ,OAAO;CAGR,MAAM,iBAAiB,IAAI,KAAK,SAAS;CAGzC,MAAM,eAAA,GAAcA,SAAAA,oBAAAA,CAAoB,gCAAgB,IAFxC,KAE0C,CAAC;CAE3D,OAAO,KAAK,IAAI,aAAa,CAAC;AAC/B"}

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { differenceInSeconds } from 'date-fns';\n\nexport const getExpirationInSeconds = (\n\texpiresAt: string | number | Date | undefined | null,\n): number => {\n\tif (!expiresAt) {\n\t\treturn 0;\n\t}\n\n\tconst expirationDate = new Date(expiresAt);\n\tconst now = new Date();\n\n\tconst secondsLeft = differenceInSeconds(expirationDate, now);\n\n\treturn Math.max(secondsLeft, 0);\n};\n\nexport interface Cache {\n\t/**\n\t * Retrieves a value from the cache.\n\t *\n\t * @param key The key to retrieve the value for.\n\t * @returns The cached value, or undefined if not found.\n\t */\n\tget<T>(key: string): Promise<T | undefined>;\n\t/**\n\t * Sets a value in the cache.\n\t *\n\t * @param key The key to set the value for.\n\t * @param value The value to cache.\n\t * @param ttl Optional time-to-live in seconds. If not provided, the value will not expire.\n\t */\n\tset<T>(key: string, value: T, ttl?: number): Promise<void>;\n\t/**\n\t * Deletes a value from the cache.\n\t *\n\t * @param key The key to delete from the cache.\n\t */\n\tdelete(key: string): Promise<void>;\n\n\t/**\n\t * Retrieves the time-to-live (TTL) for a cached value.\n\t *\n\t * @param key The key to retrieve the TTL for.\n\t * @returns The TTL in seconds, or 0 if the key does not exist.\n\t */\n\tttl(key: string): Promise<number>;\n}\n\nexport type { CacheDriver } from './registry';\nexport {\n\tcreateCacheClient,\n\tregisterCacheDriver,\n\tregisteredCacheSchemes,\n\tUnregisteredCacheScheme,\n} from './registry';\n"],"mappings":";;;AAEA,MAAa,0BACZ,cACY;CACZ,IAAI,CAAC,WACJ,OAAO;CAGR,MAAM,iBAAiB,IAAI,KAAK,SAAS;CAGzC,MAAM,cAAc,oBAAoB,gCAAgB,IAFxC,KAE0C,CAAC;CAE3D,OAAO,KAAK,IAAI,aAAa,CAAC;AAC/B"}

package/dist/postgres.cjs

@@ -1,185 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
-const require_telemetry = require("./telemetry.cjs");
-let pg = require("pg");
-pg = require_rolldown_runtime.__toESM(pg, 1);
-//#region src/postgres.ts
-/**
-* A cache that lives in a database you already have.
-*
-* The backend with no infrastructure. A cache is a table; the database is the
-* one the application already declared, so an idle stage costs nothing extra
-* and there is one fewer thing to provision, secure and pay for. It is slower
-* than Redis and that is the trade: for session lookups, rate-limit counters and
-* memoised API responses at ordinary volumes, a primary-key hit on a small table
-* is not the thing that will be slow.
-*
-* **The table is provisioned, not created on first use.** That is the one place
-* this differs from pg-boss, and the reason is the role split: a handler
-* connects as a role that may read and write rows and may not create anything,
-* so a driver issuing `CREATE TABLE` would fail on exactly the deployment where
-* the roles are doing their job. The DDL is exported instead — see
-* {@link cacheTableStatements} — and applied by whatever applies the rest.
-*
-* Reads filter on expiry and delete lazily, so an expired row is never returned
-* even if nothing has swept it; a sweep is an optimisation, not a correctness
-* requirement.
-*/
-const DEFAULT_TABLE = "cache";
-var PostgresCache = class {
-	pool;
-	table;
-	constructor(pool, options = {}) {
-		this.pool = pool;
-		this.table = options.table ?? DEFAULT_TABLE;
-	}
-	async get(key) {
-		return require_telemetry.traceCache("postgresql", "get", async () => {
-			const { rows } = await this.query(`SELECT value FROM ${this.identifier()}
-				 WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`, [key]);
-			return rows[0]?.value;
-		});
-	}
-	async set(key, value, ttl) {
-		return require_telemetry.traceCache("postgresql", "set", async () => {
-			await this.query(`INSERT INTO ${this.identifier()} (key, value, expires_at)
-				 VALUES ($1, $2::jsonb, ${ttl === void 0 ? "NULL" : "now() + ($3 || ' seconds')::interval"})
-				 ON CONFLICT (key) DO UPDATE
-				 SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at`, ttl === void 0 ? [key, JSON.stringify(value)] : [
-				key,
-				JSON.stringify(value),
-				String(ttl)
-			]);
-		});
-	}
-	async delete(key) {
-		return require_telemetry.traceCache("postgresql", "delete", async () => {
-			await this.query(`DELETE FROM ${this.identifier()} WHERE key = $1`, [key]);
-		});
-	}
-	async ttl(key) {
-		const { rows } = await this.query(`SELECT EXTRACT(EPOCH FROM (expires_at - now()))::int AS seconds
-			 FROM ${this.identifier()}
-			 WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`, [key]);
-		const row = rows[0];
-		if (!row) return 0;
-		return row.seconds ?? 0;
-	}
-	/**
-	* Delete every expired entry.
-	*
-	* Optional: reads already ignore them. Worth running occasionally so the
-	* table does not grow without bound in a workload that writes many keys once.
-	*/
-	async sweep() {
-		const { rowCount } = await this.query(`DELETE FROM ${this.identifier()} WHERE expires_at <= now()`);
-		return rowCount ?? 0;
-	}
-	async query(sql, values = []) {
-		const result = await this.pool.query(sql, values);
-		return {
-			rows: result.rows,
-			rowCount: result.rowCount
-		};
-	}
-	/**
-	* The table name as an identifier.
-	*
-	* Quoted per segment so a schema-qualified name stays two identifiers rather
-	* than becoming one with a dot in it. The name comes from configuration
-	* rather than from a request, so this is defence rather than sanitisation.
-	*/
-	identifier() {
-		return quote(this.table);
-	}
-};
-/**
-* The `postgres://` driver.
-*
-* One pool per URL, cached for the life of the process: a cache that opened a
-* connection per call would be slower than the thing it exists to speed up, and
-* a Lambda reusing a warm container should reuse the pool with it.
-*
-* `pg` is imported at the top of this module rather than lazily, because the
-* *module* is the lazy boundary — an app caching in Redis never imports
-* `@geekmidas/cache/postgres` and so never resolves the driver behind it. Same
-* arrangement `@geekmidas/storage/aws` uses for the AWS SDK.
-*/
-const postgresCacheDriver = {
-	scheme: "postgres:",
-	create(url) {
-		const { connectionString, table } = split(url);
-		const existing = pools.get(connectionString);
-		const pool = existing ?? new pg.default.Pool({ connectionString });
-		if (!existing) pools.set(connectionString, pool);
-		return new PostgresCache(pool, table ? { table } : {});
-	}
-};
-/**
-* A cache URL as its two facts: where to connect, and what to read.
-*
-* `table` is removed from the string handed to `pg` rather than left on it,
-* because a Postgres connection string carries libpq parameters and an unknown
-* one is not guaranteed to be ignored — and because the pool should be shared
-* by every cache in the database, which only works if the key does not vary
-* per cache.
-*/
-function split(url) {
-	try {
-		const parsed = new URL(url);
-		const table = parsed.searchParams.get("table") ?? void 0;
-		if (!table) return { connectionString: url };
-		parsed.searchParams.delete("table");
-		return {
-			connectionString: parsed.toString(),
-			table
-		};
-	} catch {
-		return { connectionString: url };
-	}
-}
-const pools = /* @__PURE__ */ new Map();
-/**
-* The DDL a Postgres-backed cache needs, for whoever applies DDL.
-*
-* Generation only, in the shape `@geekmidas/db/pg/roles` uses — the same
-* statements run in-process from `gkm dev` and from a provisioner inside a VPC,
-* and one implementation is what stops "works locally, fails deployed".
-*
-* Run as the schema's **owner**. The role a handler connects as cannot create a
-* table, which is the point of the split and the reason this is not done lazily.
-*/
-function cacheTableStatements(options = {}) {
-	const table = options.table ?? DEFAULT_TABLE;
-	const [schema, name] = table.includes(".") ? table.split(".") : [void 0, table];
-	const qualified = quote(table);
-	return [{
-		describe: `cache table ${table}`,
-		exists: {
-			sql: schema ? "SELECT 1 FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2" : "SELECT 1 FROM information_schema.tables WHERE table_name = $1",
-			values: schema ? [schema, name] : [name]
-		},
-		sql: `CREATE TABLE ${qualified} (
-				key text PRIMARY KEY,
-				value jsonb NOT NULL,
-				expires_at timestamptz
-			)`
-	}, {
-		describe: `cache expiry index on ${table}`,
-		sql: `CREATE INDEX IF NOT EXISTS ${indexName(table)}
-			      ON ${qualified} (expires_at) WHERE expires_at IS NOT NULL`
-	}];
-}
-/** A possibly schema-qualified name, quoted per segment. */
-function quote(table) {
-	return table.split(".").map((part) => `"${part.replace(/"/g, "\"\"")}"`).join(".");
-}
-function indexName(table) {
-	return `"${table.replace(/[^a-zA-Z0-9]/g, "_")}_expires_at_idx"`;
-}
-//#endregion
-exports.PostgresCache = PostgresCache;
-exports.cacheTableStatements = cacheTableStatements;
-exports.postgresCacheDriver = postgresCacheDriver;
-
-//# sourceMappingURL=postgres.cjs.map

package/dist/postgres.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"postgres.cjs","names":["traceCache"],"sources":["../src/postgres.ts"],"sourcesContent":["/**\n * A cache that lives in a database you already have.\n *\n * The backend with no infrastructure. A cache is a table; the database is the\n * one the application already declared, so an idle stage costs nothing extra\n * and there is one fewer thing to provision, secure and pay for. It is slower\n * than Redis and that is the trade: for session lookups, rate-limit counters and\n * memoised API responses at ordinary volumes, a primary-key hit on a small table\n * is not the thing that will be slow.\n *\n * **The table is provisioned, not created on first use.** That is the one place\n * this differs from pg-boss, and the reason is the role split: a handler\n * connects as a role that may read and write rows and may not create anything,\n * so a driver issuing `CREATE TABLE` would fail on exactly the deployment where\n * the roles are doing their job. The DDL is exported instead — see\n * {@link cacheTableStatements} — and applied by whatever applies the rest.\n *\n * Reads filter on expiry and delete lazily, so an expired row is never returned\n * even if nothing has swept it; a sweep is an optimisation, not a correctness\n * requirement.\n */\n\nimport pg, { type Pool } from 'pg';\nimport type { Cache } from './index';\nimport type { CacheDriver } from './registry';\nimport { traceCache } from './telemetry';\n\nexport interface PostgresCacheOptions {\n\t/**\n\t * The table to keep entries in, schema-qualified if it needs to be.\n\t *\n\t * Defaults to `cache`. It resolves against the connection's `search_path`,\n\t * which the role carries — so a tenant's cache lands in the tenant's schema\n\t * without anything here knowing the schema's name.\n\t */\n\ttable?: string;\n}\n\nconst DEFAULT_TABLE = 'cache';\n\nexport class PostgresCache implements Cache {\n\tprivate readonly table: string;\n\n\tconstructor(\n\t\tprivate readonly pool: Pool,\n\t\toptions: PostgresCacheOptions = {},\n\t) {\n\t\tthis.table = options.table ?? DEFAULT_TABLE;\n\t}\n\n\tasync get<T>(key: string): Promise<T | undefined> {\n\t\treturn traceCache('postgresql', 'get', async () => {\n\t\t\tconst { rows } = await this.query<{ value: T }>(\n\t\t\t\t`SELECT value FROM ${this.identifier()}\n\t\t\t\t WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`,\n\t\t\t\t[key],\n\t\t\t);\n\n\t\t\treturn rows[0]?.value;\n\t\t});\n\t}\n\n\tasync set<T>(key: string, value: T, ttl?: number): Promise<void> {\n\t\treturn traceCache('postgresql', 'set', async () => {\n\t\t\t// `now() + interval` computed by the server, not by this process: a\n\t\t\t// client whose clock is minutes off would otherwise write entries that\n\t\t\t// expire early or late, and clock skew is not a thing to debug through a\n\t\t\t// cache.\n\t\t\tawait this.query(\n\t\t\t\t`INSERT INTO ${this.identifier()} (key, value, expires_at)\n\t\t\t\t VALUES ($1, $2::jsonb, ${ttl === undefined ? 'NULL' : \"now() + ($3 || ' seconds')::interval\"})\n\t\t\t\t ON CONFLICT (key) DO UPDATE\n\t\t\t\t SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at`,\n\t\t\t\tttl === undefined\n\t\t\t\t\t? [key, JSON.stringify(value)]\n\t\t\t\t\t: [key, JSON.stringify(value), String(ttl)],\n\t\t\t);\n\t\t});\n\t}\n\n\tasync delete(key: string): Promise<void> {\n\t\treturn traceCache('postgresql', 'delete', async () => {\n\t\t\tawait this.query(`DELETE FROM ${this.identifier()} WHERE key = $1`, [\n\t\t\t\tkey,\n\t\t\t]);\n\t\t});\n\t}\n\n\tasync ttl(key: string): Promise<number> {\n\t\tconst { rows } = await this.query<{ seconds: number | null }>(\n\t\t\t`SELECT EXTRACT(EPOCH FROM (expires_at - now()))::int AS seconds\n\t\t\t FROM ${this.identifier()}\n\t\t\t WHERE key = $1 AND (expires_at IS NULL OR expires_at > now())`,\n\t\t\t[key],\n\t\t);\n\n\t\tconst row = rows[0];\n\t\tif (!row) return 0;\n\n\t\t// A row with no expiry has no time *left* to report. Zero is what the\n\t\t// interface says a missing key returns, and \"never expires\" is closer to\n\t\t// that than to any number this could invent.\n\t\treturn row.seconds ?? 0;\n\t}\n\n\t/**\n\t * Delete every expired entry.\n\t *\n\t * Optional: reads already ignore them. Worth running occasionally so the\n\t * table does not grow without bound in a workload that writes many keys once.\n\t */\n\tasync sweep(): Promise<number> {\n\t\tconst { rowCount } = await this.query(\n\t\t\t`DELETE FROM ${this.identifier()} WHERE expires_at <= now()`,\n\t\t);\n\n\t\treturn rowCount ?? 0;\n\t}\n\n\tprivate async query<T>(\n\t\tsql: string,\n\t\tvalues: unknown[] = [],\n\t): Promise<{ rows: T[]; rowCount: number | null }> {\n\t\tconst result = await this.pool.query(sql, values);\n\n\t\treturn { rows: result.rows as T[], rowCount: result.rowCount };\n\t}\n\n\t/**\n\t * The table name as an identifier.\n\t *\n\t * Quoted per segment so a schema-qualified name stays two identifiers rather\n\t * than becoming one with a dot in it. The name comes from configuration\n\t * rather than from a request, so this is defence rather than sanitisation.\n\t */\n\tprivate identifier(): string {\n\t\treturn quote(this.table);\n\t}\n}\n\n/**\n * The `postgres://` driver.\n *\n * One pool per URL, cached for the life of the process: a cache that opened a\n * connection per call would be slower than the thing it exists to speed up, and\n * a Lambda reusing a warm container should reuse the pool with it.\n *\n * `pg` is imported at the top of this module rather than lazily, because the\n * *module* is the lazy boundary — an app caching in Redis never imports\n * `@geekmidas/cache/postgres` and so never resolves the driver behind it. Same\n * arrangement `@geekmidas/storage/aws` uses for the AWS SDK.\n */\nexport const postgresCacheDriver: CacheDriver = {\n\tscheme: 'postgres:',\n\tcreate(url) {\n\t\t// The table travels in the URL, the way pg-boss's schema does.\n\t\t//\n\t\t// It has to, because a database-backed cache has no address of its own:\n\t\t// two caches in one database resolve the *same* connection string, so a\n\t\t// client built from the URL alone cannot tell them apart and both would\n\t\t// read and write one table — sharing a keyspace and evicting each other's\n\t\t// keys. The parameter is what makes the address identify the cache.\n\t\tconst { connectionString, table } = split(url);\n\n\t\tconst existing = pools.get(connectionString);\n\t\tconst pool = existing ?? new pg.Pool({ connectionString });\n\t\tif (!existing) pools.set(connectionString, pool);\n\n\t\t// One pool per database, shared by every cache in it — the table is the\n\t\t// client's, not the pool's.\n\t\treturn new PostgresCache(pool, table ? { table } : {});\n\t},\n};\n\n/**\n * A cache URL as its two facts: where to connect, and what to read.\n *\n * `table` is removed from the string handed to `pg` rather than left on it,\n * because a Postgres connection string carries libpq parameters and an unknown\n * one is not guaranteed to be ignored — and because the pool should be shared\n * by every cache in the database, which only works if the key does not vary\n * per cache.\n */\nfunction split(url: string): { connectionString: string; table?: string } {\n\ttry {\n\t\tconst parsed = new URL(url);\n\t\tconst table = parsed.searchParams.get('table') ?? undefined;\n\n\t\tif (!table) return { connectionString: url };\n\n\t\tparsed.searchParams.delete('table');\n\n\t\treturn { connectionString: parsed.toString(), table };\n\t} catch {\n\t\t// Not a URL `URL` can parse. The driver's job is not to validate one, so\n\t\t// this hands it to `pg` unchanged and lets that failure be the one\n\t\t// reported.\n\t\treturn { connectionString: url };\n\t}\n}\n\nconst pools = new Map<string, Pool>();\n\n/**\n * The DDL a Postgres-backed cache needs, for whoever applies DDL.\n *\n * Generation only, in the shape `@geekmidas/db/pg/roles` uses — the same\n * statements run in-process from `gkm dev` and from a provisioner inside a VPC,\n * and one implementation is what stops \"works locally, fails deployed\".\n *\n * Run as the schema's **owner**. The role a handler connects as cannot create a\n * table, which is the point of the split and the reason this is not done lazily.\n */\nexport function cacheTableStatements(options: PostgresCacheOptions = {}): {\n\tdescribe: string;\n\texists?: { sql: string; values: unknown[] };\n\tsql: string;\n}[] {\n\tconst table = options.table ?? DEFAULT_TABLE;\n\tconst [schema, name] = table.includes('.')\n\t\t? (table.split('.') as [string, string])\n\t\t: [undefined, table];\n\tconst qualified = quote(table);\n\n\treturn [\n\t\t{\n\t\t\tdescribe: `cache table ${table}`,\n\t\t\texists: {\n\t\t\t\tsql: schema\n\t\t\t\t\t? 'SELECT 1 FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2'\n\t\t\t\t\t: 'SELECT 1 FROM information_schema.tables WHERE table_name = $1',\n\t\t\t\tvalues: schema ? [schema, name] : [name],\n\t\t\t},\n\t\t\tsql: `CREATE TABLE ${qualified} (\n\t\t\t\tkey text PRIMARY KEY,\n\t\t\t\tvalue jsonb NOT NULL,\n\t\t\t\texpires_at timestamptz\n\t\t\t)`,\n\t\t},\n\t\t{\n\t\t\t// Only the expiring rows: a partial index stays small in a cache whose\n\t\t\t// entries mostly never expire, and the sweep only ever looks at those.\n\t\t\tdescribe: `cache expiry index on ${table}`,\n\t\t\tsql: `CREATE INDEX IF NOT EXISTS ${indexName(table)}\n\t\t\t      ON ${qualified} (expires_at) WHERE expires_at IS NOT NULL`,\n\t\t},\n\t];\n}\n\n/** A possibly schema-qualified name, quoted per segment. */\nfunction quote(table: string): string {\n\treturn table\n\t\t.split('.')\n\t\t.map((part) => `\"${part.replace(/\"/g, '\"\"')}\"`)\n\t\t.join('.');\n}\n\nfunction indexName(table: string): string {\n\treturn `\"${table.replace(/[^a-zA-Z0-9]/g, '_')}_expires_at_idx\"`;\n}\n"],"mappings":"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"}

package/dist/postgres.d.cts

@@ -1,71 +0,0 @@
-import { r as CacheDriver, t as Cache } from "./index-BbdGhmWP.cjs";
-import { Pool } from "pg";
-//#region src/postgres.d.ts
-export interface PostgresCacheOptions {
-  /**
-   * The table to keep entries in, schema-qualified if it needs to be.
-   *
-   * Defaults to `cache`. It resolves against the connection's `search_path`,
-   * which the role carries — so a tenant's cache lands in the tenant's schema
-   * without anything here knowing the schema's name.
-   */
-  table?: string;
-}
-export declare class PostgresCache implements Cache {
-  private readonly pool;
-  private readonly table;
-  constructor(pool: Pool, options?: PostgresCacheOptions);
-  get<T>(key: string): Promise<T | undefined>;
-  set<T>(key: string, value: T, ttl?: number): Promise<void>;
-  delete(key: string): Promise<void>;
-  ttl(key: string): Promise<number>;
-  /**
-   * Delete every expired entry.
-   *
-   * Optional: reads already ignore them. Worth running occasionally so the
-   * table does not grow without bound in a workload that writes many keys once.
-   */
-  sweep(): Promise<number>;
-  private query;
-  /**
-   * The table name as an identifier.
-   *
-   * Quoted per segment so a schema-qualified name stays two identifiers rather
-   * than becoming one with a dot in it. The name comes from configuration
-   * rather than from a request, so this is defence rather than sanitisation.
-   */
-  private identifier;
-}
-/**
- * The `postgres://` driver.
- *
- * One pool per URL, cached for the life of the process: a cache that opened a
- * connection per call would be slower than the thing it exists to speed up, and
- * a Lambda reusing a warm container should reuse the pool with it.
- *
- * `pg` is imported at the top of this module rather than lazily, because the
- * *module* is the lazy boundary — an app caching in Redis never imports
- * `@geekmidas/cache/postgres` and so never resolves the driver behind it. Same
- * arrangement `@geekmidas/storage/aws` uses for the AWS SDK.
- */
-export declare const postgresCacheDriver: CacheDriver;
-/**
- * The DDL a Postgres-backed cache needs, for whoever applies DDL.
- *
- * Generation only, in the shape `@geekmidas/db/pg/roles` uses — the same
- * statements run in-process from `gkm dev` and from a provisioner inside a VPC,
- * and one implementation is what stops "works locally, fails deployed".
- *
- * Run as the schema's **owner**. The role a handler connects as cannot create a
- * table, which is the point of the split and the reason this is not done lazily.
- */
-export declare function cacheTableStatements(options?: PostgresCacheOptions): {
-  describe: string;
-  exists?: {
-    sql: string;
-    values: unknown[];
-  };
-  sql: string;
-}[];
-//#endregion
-//# sourceMappingURL=postgres.d.cts.map

package/dist/postgres.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"postgres.d.cts","names":[],"sources":["../src/postgres.ts"],"mappings":";;;iBA2BiB;;;;;;;;EAQhB;;qBAKY,yBAAyB;mBAInB;mBAHD;EAEjB,YACkB,MAAM,MACvB,UAAS;EAKJ,IAAI,GAAG,cAAc,QAAQ;EAY7B,IAAI,GAAG,aAAa,OAAO,GAAG,eAAe;EAkB7C,OAAO,cAAc;EAQrB,IAAI,cAAc;;;;;;;EAuBlB,SAAS;UAQD;;;;;;;;UAgBN;;;;;;;;;;;;;;qBAiBI,qBAAqB;;;;;;;;;;;wBA6DlB,qBAAqB,UAAS;EAC7C;EACA;IAAW;IAAa;;EACxB"}

package/dist/postgres.d.mts

@@ -1,71 +0,0 @@
-import { r as CacheDriver, t as Cache } from "./index-BbdGhmWP.mjs";
-import { Pool } from "pg";
-//#region src/postgres.d.ts
-export interface PostgresCacheOptions {
-  /**
-   * The table to keep entries in, schema-qualified if it needs to be.
-   *
-   * Defaults to `cache`. It resolves against the connection's `search_path`,
-   * which the role carries — so a tenant's cache lands in the tenant's schema
-   * without anything here knowing the schema's name.
-   */
-  table?: string;
-}
-export declare class PostgresCache implements Cache {
-  private readonly pool;
-  private readonly table;
-  constructor(pool: Pool, options?: PostgresCacheOptions);
-  get<T>(key: string): Promise<T | undefined>;
-  set<T>(key: string, value: T, ttl?: number): Promise<void>;
-  delete(key: string): Promise<void>;
-  ttl(key: string): Promise<number>;
-  /**
-   * Delete every expired entry.
-   *
-   * Optional: reads already ignore them. Worth running occasionally so the
-   * table does not grow without bound in a workload that writes many keys once.
-   */
-  sweep(): Promise<number>;
-  private query;
-  /**
-   * The table name as an identifier.
-   *
-   * Quoted per segment so a schema-qualified name stays two identifiers rather
-   * than becoming one with a dot in it. The name comes from configuration
-   * rather than from a request, so this is defence rather than sanitisation.
-   */
-  private identifier;
-}
-/**
- * The `postgres://` driver.
- *
- * One pool per URL, cached for the life of the process: a cache that opened a
- * connection per call would be slower than the thing it exists to speed up, and
- * a Lambda reusing a warm container should reuse the pool with it.
- *
- * `pg` is imported at the top of this module rather than lazily, because the
- * *module* is the lazy boundary — an app caching in Redis never imports
- * `@geekmidas/cache/postgres` and so never resolves the driver behind it. Same
- * arrangement `@geekmidas/storage/aws` uses for the AWS SDK.
- */
-export declare const postgresCacheDriver: CacheDriver;
-/**
- * The DDL a Postgres-backed cache needs, for whoever applies DDL.
- *
- * Generation only, in the shape `@geekmidas/db/pg/roles` uses — the same
- * statements run in-process from `gkm dev` and from a provisioner inside a VPC,
- * and one implementation is what stops "works locally, fails deployed".
- *
- * Run as the schema's **owner**. The role a handler connects as cannot create a
- * table, which is the point of the split and the reason this is not done lazily.
- */
-export declare function cacheTableStatements(options?: PostgresCacheOptions): {
-  describe: string;
-  exists?: {
-    sql: string;
-    values: unknown[];
-  };
-  sql: string;
-}[];
-//#endregion
-//# sourceMappingURL=postgres.d.mts.map

package/dist/postgres.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"postgres.d.mts","names":[],"sources":["../src/postgres.ts"],"mappings":";;;iBA2BiB;;;;;;;;EAQhB;;qBAKY,yBAAyB;mBAInB;mBAHD;EAEjB,YACkB,MAAM,MACvB,UAAS;EAKJ,IAAI,GAAG,cAAc,QAAQ;EAY7B,IAAI,GAAG,aAAa,OAAO,GAAG,eAAe;EAkB7C,OAAO,cAAc;EAQrB,IAAI,cAAc;;;;;;;EAuBlB,SAAS;UAQD;;;;;;;;UAgBN;;;;;;;;;;;;;;qBAiBI,qBAAqB;;;;;;;;;;;wBA6DlB,qBAAqB,UAAS;EAC7C;EACA;IAAW;IAAa;;EACxB"}