@b4moss/ss-cachian 0.7.0 → 0.9.0

package/README.md

@@ -2,15 +2,51 @@
 
 TypeScript / JavaScript port of [ss-cachian](https://github.com/b4moss/ss-cachian).
 
-> **Status:** package scaffold for npm release path. Cache Type API is not implemented yet.
-> Go PoC is complete at `go/sscachian` (**v0.7.0**). Specs: [docs/specs](../../docs/specs/).
+Semantics match the Go package at `go/sscachian` (**v0.9.0**): versioned keys, multilayer
+write-back, Exact Purge, Memory / Firestore drivers, and **config-driven** `loadTypes`.
+Specs: [docs/specs](../../docs/specs/).
 
-## Install (after first publish)
+## Install
 
 ```bash
 npm install @b4moss/ss-cachian
 ```
 
+## Quick start
+
+```ts
+import { define, newMemoryStore, defaultKeyBuilder } from "@b4moss/ss-cachian";
+
+const cache = define<string>("users")
+  .withLayers(newMemoryStore())
+  .withKeyBuilder(defaultKeyBuilder)
+  .build();
+
+const kc = { appSlug: "app", tenantId: "t1", queryType: "user" };
+await cache.set(kc, "alice");
+const got = await cache.get(kc); // { ok: true, value: "alice" }
+```
+
+### Config-driven (v0.9.0)
+
+```ts
+import { createRegistry, loadTypes } from "@b4moss/ss-cachian";
+
+const reg = createRegistry();
+reg.registerLoader("load_users", async () => "alice");
+const types = await loadTypes(reg, "./sscachian.yaml");
+const cache = types.get("users");
+```
+
+Firestore (Emulator / GCP):
+
+```ts
+import { define, newFirestoreStore, newMemoryStore } from "@b4moss/ss-cachian";
+
+const fs = await newFirestoreStore({ projectId: "my-project" });
+const cache = define("users").withLayers(newMemoryStore(), fs).build();
+```
+
 ## Develop
 
 ```bash
@@ -18,10 +54,10 @@ cd node/sscachian
 npm ci
 npm run lint
 npm test
-npm run build
+# Firestore tests need FIRESTORE_EMULATOR_HOST (CI starts the emulator)
 ```
 
 ## Publish
 
-Tags `v*` on `main` trigger `.github/workflows/npm-publish.yml` (`npm publish`).
-Version is taken from the tag (`v0.8.0` → `0.8.0`). Requires repo secret `NPM_TOKEN` (npm Granular Access Token).
+Tags `v*` on `main` (or Actions → **npm publish** → Run workflow) publish via
+**npm Trusted Publisher (OIDC)**. See [.github/CI.md](../../.github/CI.md).

package/dist/cache.d.ts

@@ -0,0 +1,39 @@
+import { type DurationMs, type KeyBuilder, type KeyContext, type Layer, type Loader, type TypeGuard } from "./types.js";
+export declare class Builder<T> {
+    #private;
+    constructor(name: string);
+    withLayers(...layers: Layer[]): this;
+    withKeyBuilder(kb: KeyBuilder | null): this;
+    withLayerTTL(ttl: DurationMs): this;
+    withPolicy(ttl: DurationMs): this;
+    withLayerTTLs(...ttls: DurationMs[]): this;
+    withLoader(loader: Loader<T>): this;
+    /** Optional runtime type check on Get (Go type assertion equivalent). */
+    withTypeGuard(guard: TypeGuard<T>): this;
+    build(): CacheType<T>;
+}
+export declare function define<T = unknown>(name: string): Builder<T>;
+export declare class CacheType<T> {
+    #private;
+    constructor(name: string, layers: Layer[], ttls: DurationMs[], kb: KeyBuilder, loader: Loader<T> | null, guard?: TypeGuard<T>);
+    name(): string;
+    layers(): Layer[];
+    layerTTL(i: number): DurationMs;
+    buildKey(kc: KeyContext, version: number, signal?: AbortSignal): Promise<string>;
+    versionKey(kc: KeyContext, signal?: AbortSignal): Promise<string>;
+    currentVersion(kc: KeyContext, signal?: AbortSignal): Promise<number>;
+    bumpVersion(kc: KeyContext, signal?: AbortSignal): Promise<number>;
+    buildLatestKey(kc: KeyContext, signal?: AbortSignal): Promise<string>;
+    get(kc: KeyContext, signal?: AbortSignal): Promise<{
+        value: T;
+        ok: true;
+    } | {
+        value?: undefined;
+        ok: false;
+    }>;
+    set(kc: KeyContext, value: T, signal?: AbortSignal): Promise<void>;
+    delete(kc: KeyContext, signal?: AbortSignal): Promise<void>;
+    purge(kc: KeyContext, layerIdx?: number[], signal?: AbortSignal): Promise<void>;
+    getOrLoad(kc: KeyContext, signal?: AbortSignal): Promise<T>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,SAAS,EAUf,MAAM,YAAY,CAAC;AA4BpB,qBAAa,OAAO,CAAC,CAAC;;gBASR,IAAI,EAAE,MAAM;IAIxB,UAAU,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAKpC,cAAc,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI;IAK3C,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAKnC,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAIjC,aAAa,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI;IAM1C,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI;IAKnC,yEAAyE;IACzE,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAKxC,KAAK,IAAI,SAAS,CAAC,CAAC,CAAC;CAyBtB;AAED,wBAAgB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAE5D;AAED,qBAAa,SAAS,CAAC,CAAC;;gBASpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,KAAK,EAAE,EACf,IAAI,EAAE,UAAU,EAAE,EAClB,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,EACxB,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IAUtB,IAAI,IAAI,MAAM;IAId,MAAM,IAAI,KAAK,EAAE;IAIjB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU;IAazB,QAAQ,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAMhF,UAAU,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAavE,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/D,WAAW,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAMlE,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAyBrE,GAAG,CACP,EAAE,EAAE,UAAU,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,KAAK,CAAC,EAAE,SAAS,CAAC;QAAC,EAAE,EAAE,KAAK,CAAA;KAAE,CAAC;IAY/D,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAelE,MAAM,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,GAAE,MAAM,EAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCnF,SAAS,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAUlE"}

package/dist/cache.js

@@ -0,0 +1,269 @@
+import { ErrCorruptVersion, ErrInvalidLayerIndex, ErrInvalidVersion, ErrNoKeyBuilder, ErrNoLayer, ErrNoLoader, ErrNegativeTTL, ErrTypeMismatch, defaultKeyBuilder, } from "./types.js";
+function logWarn(msg, err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    console.warn(msg, detail);
+}
+function asInt64(v) {
+    if (typeof v === "number") {
+        if (!Number.isInteger(v))
+            throw ErrCorruptVersion;
+        return v;
+    }
+    if (typeof v === "bigint") {
+        const n = Number(v);
+        if (!Number.isSafeInteger(n))
+            throw ErrCorruptVersion;
+        return n;
+    }
+    throw ErrCorruptVersion;
+}
+function castValue(v, guard) {
+    if (guard) {
+        if (!guard(v))
+            throw ErrTypeMismatch;
+        return v;
+    }
+    return v;
+}
+export class Builder {
+    #name;
+    #layers = [];
+    #ttls = [];
+    #single = null;
+    #kb = defaultKeyBuilder;
+    #loader = null;
+    #guard;
+    constructor(name) {
+        this.#name = name;
+    }
+    withLayers(...layers) {
+        this.#layers = [...layers];
+        return this;
+    }
+    withKeyBuilder(kb) {
+        this.#kb = kb;
+        return this;
+    }
+    withLayerTTL(ttl) {
+        this.#single = ttl;
+        return this;
+    }
+    withPolicy(ttl) {
+        return this.withLayerTTL(ttl);
+    }
+    withLayerTTLs(...ttls) {
+        this.#ttls = [...ttls];
+        this.#single = null;
+        return this;
+    }
+    withLoader(loader) {
+        this.#loader = loader;
+        return this;
+    }
+    /** Optional runtime type check on Get (Go type assertion equivalent). */
+    withTypeGuard(guard) {
+        this.#guard = guard;
+        return this;
+    }
+    build() {
+        if (this.#layers.length === 0)
+            throw ErrNoLayer;
+        if (this.#kb == null)
+            throw ErrNoKeyBuilder;
+        const ttls = new Array(this.#layers.length).fill(0);
+        if (this.#single != null) {
+            if (this.#single < 0)
+                throw ErrNegativeTTL;
+            for (let i = 0; i < ttls.length; i++)
+                ttls[i] = this.#single;
+        }
+        else {
+            for (let i = 0; i < ttls.length; i++) {
+                if (i < this.#ttls.length) {
+                    const t = this.#ttls[i];
+                    if (t < 0)
+                        throw ErrNegativeTTL;
+                    ttls[i] = t;
+                }
+            }
+        }
+        return new CacheType(this.#name, [...this.#layers], ttls, this.#kb, this.#loader, this.#guard);
+    }
+}
+export function define(name) {
+    return new Builder(name);
+}
+export class CacheType {
+    #name;
+    #layers;
+    #ttls;
+    #kb;
+    #loader;
+    #guard;
+    constructor(name, layers, ttls, kb, loader, guard) {
+        this.#name = name;
+        this.#layers = layers;
+        this.#ttls = ttls;
+        this.#kb = kb;
+        this.#loader = loader;
+        this.#guard = guard;
+    }
+    name() {
+        return this.#name;
+    }
+    layers() {
+        return [...this.#layers];
+    }
+    layerTTL(i) {
+        if (i < 0 || i >= this.#ttls.length)
+            return 0;
+        return this.#ttls[i];
+    }
+    #l1() {
+        return this.#layers[0];
+    }
+    async #logicalPrefix(kc, signal) {
+        return await this.#kb(kc, signal);
+    }
+    async buildKey(kc, version, signal) {
+        if (version < 1)
+            throw ErrInvalidVersion;
+        const prefix = await this.#logicalPrefix(kc, signal);
+        return `${prefix}:${version}`;
+    }
+    async versionKey(kc, signal) {
+        const prefix = await this.#logicalPrefix(kc, signal);
+        return `${prefix}:__version__`;
+    }
+    async #ensureCurrentVersion(kc, signal) {
+        const vk = await this.versionKey(kc, signal);
+        const { entry, hit } = await this.#l1().get(vk, signal);
+        if (hit)
+            return asInt64(entry.value);
+        await this.#l1().set(vk, { value: 1, createdAt: new Date(0), expiresAt: null }, 0, signal);
+        return 1;
+    }
+    currentVersion(kc, signal) {
+        return this.#ensureCurrentVersion(kc, signal);
+    }
+    async bumpVersion(kc, signal) {
+        const vk = await this.versionKey(kc, signal);
+        await this.#ensureCurrentVersion(kc, signal);
+        return this.#l1().incr(vk, signal);
+    }
+    async buildLatestKey(kc, signal) {
+        const v = await this.#ensureCurrentVersion(kc, signal);
+        return this.buildKey(kc, v, signal);
+    }
+    async #writeBack(key, e, upToExclusive, signal) {
+        for (let j = 0; j < upToExclusive; j++) {
+            try {
+                await this.#layers[j].set(key, e, this.layerTTL(j), signal);
+            }
+            catch (err) {
+                logWarn(`sscachian: write-back to layer ${j} failed:`, err);
+            }
+        }
+    }
+    async #writeAll(key, e, signal) {
+        for (let i = 0; i < this.#layers.length; i++) {
+            try {
+                await this.#layers[i].set(key, e, this.layerTTL(i), signal);
+            }
+            catch (err) {
+                logWarn(`sscachian: write-back to layer ${i} failed:`, err);
+            }
+        }
+    }
+    async get(kc, signal) {
+        const key = await this.buildLatestKey(kc, signal);
+        for (let i = 0; i < this.#layers.length; i++) {
+            const { entry, hit } = await this.#layers[i].get(key, signal);
+            if (!hit)
+                continue;
+            await this.#writeBack(key, entry, i, signal);
+            const tv = castValue(entry.value, this.#guard);
+            return { value: tv, ok: true };
+        }
+        return { ok: false };
+    }
+    async set(kc, value, signal) {
+        await this.#ensureCurrentVersion(kc, signal);
+        const newV = await this.bumpVersion(kc, signal);
+        const key = await this.buildKey(kc, newV, signal);
+        const entry = { value, createdAt: new Date(0), expiresAt: null };
+        await this.#l1().set(key, entry, this.layerTTL(0), signal);
+        for (let i = 1; i < this.#layers.length; i++) {
+            try {
+                await this.#layers[i].set(key, entry, this.layerTTL(i), signal);
+            }
+            catch (err) {
+                logWarn(`sscachian: set layer ${i} failed:`, err);
+            }
+        }
+    }
+    async delete(kc, signal) {
+        const v = await this.#ensureCurrentVersion(kc, signal);
+        const key = await this.buildKey(kc, v, signal);
+        await this.#l1().delete(key, signal);
+        for (let i = 1; i < this.#layers.length; i++) {
+            try {
+                await this.#layers[i].delete(key, signal);
+            }
+            catch (err) {
+                logWarn(`sscachian: delete layer ${i} failed:`, err);
+            }
+        }
+        await this.bumpVersion(kc, signal);
+    }
+    async purge(kc, layerIdx = [], signal) {
+        const prefix = await this.#logicalPrefix(kc, signal);
+        const targets = this.#resolveLayerIndexes(layerIdx);
+        const includesL1 = targets.includes(0);
+        for (const i of targets) {
+            try {
+                await this.#layers[i].purgeExact(prefix, signal);
+            }
+            catch (err) {
+                if (includesL1) {
+                    if (i === 0)
+                        throw err;
+                    logWarn(`sscachian: purge layer ${i} failed:`, err);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    #resolveLayerIndexes(layerIdx) {
+        const n = this.#layers.length;
+        if (layerIdx.length === 0) {
+            return Array.from({ length: n }, (_, i) => i);
+        }
+        const seen = new Set();
+        const out = [];
+        for (const i of layerIdx) {
+            if (i < 0 || i >= n)
+                throw ErrInvalidLayerIndex;
+            if (seen.has(i))
+                continue;
+            seen.add(i);
+            out.push(i);
+        }
+        out.sort((a, b) => a - b);
+        return out;
+    }
+    async getOrLoad(kc, signal) {
+        const got = await this.get(kc, signal);
+        if (got.ok)
+            return got.value;
+        if (this.#loader == null)
+            throw ErrNoLoader;
+        const loaded = await this.#loader(kc, signal);
+        const ver = await this.#ensureCurrentVersion(kc, signal);
+        const key = await this.buildKey(kc, ver, signal);
+        await this.#writeAll(key, { value: loaded, createdAt: new Date(0), expiresAt: null }, signal);
+        return loaded;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import { CacheType } from "./cache.js";
+import { type DurationMs, type KeyBuilder, type Loader } from "./types.js";
+export type Registry = {
+    registerKeyBuilder(name: string, kb: KeyBuilder): void;
+    registerLoader<T>(name: string, loader: Loader<T>): void;
+    /** @internal */
+    lookupKeyBuilder(name: string): KeyBuilder | undefined;
+    /** @internal */
+    lookupLoader(name: string): Loader<unknown> | undefined;
+};
+export declare function createRegistry(): Registry;
+/** Go time.ParseDuration-compatible parser (ns/us/ms/s/m/h). */
+export declare function parseDuration(s: string): DurationMs;
+export declare function loadTypesYAML<T = unknown>(reg: Registry, data: string | Uint8Array): Promise<Map<string, CacheType<T>>>;
+export declare function loadTypesJSON<T = unknown>(reg: Registry, data: string | Uint8Array): Promise<Map<string, CacheType<T>>>;
+export declare function loadTypes<T = unknown>(reg: Registry, filePath: string): Promise<Map<string, CacheType<T>>>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAU,MAAM,YAAY,CAAC;AAG/C,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,UAAU,EAEf,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,QAAQ,GAAG;IACrB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,CAAC;IACvD,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACzD,gBAAgB;IAChB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACvD,gBAAgB;IAChB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;CACzD,CAAC;AAEF,wBAAgB,cAAc,IAAI,QAAQ,CAsBzC;AAqBD,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CA2BnD;AAoID,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7C,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,GAAG,UAAU,GACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CASpC;AAED,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7C,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,GAAG,UAAU,GACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CASpC;AAED,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAMpC"}

package/dist/config.js

@@ -0,0 +1,223 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { define } from "./cache.js";
+import { newFirestoreStore } from "./driver/firestore.js";
+import { newMemoryStore } from "./driver/memory.js";
+import { ErrInvalidConfig, ErrNegativeTTL, defaultKeyBuilder, } from "./types.js";
+const SCHEMA_VERSION = "0.9";
+export function createRegistry() {
+    const keyBuilders = new Map([["default", defaultKeyBuilder]]);
+    const loaders = new Map();
+    return {
+        registerKeyBuilder(name, kb) {
+            if (!name)
+                throw new Error(`${ErrInvalidConfig.message}: empty key builder name`);
+            if (kb == null)
+                throw new Error(`${ErrInvalidConfig.message}: nil key builder`);
+            keyBuilders.set(name, kb);
+        },
+        registerLoader(name, loader) {
+            if (!name)
+                throw new Error(`${ErrInvalidConfig.message}: empty loader name`);
+            if (loader == null)
+                throw new Error(`${ErrInvalidConfig.message}: nil loader`);
+            loaders.set(name, loader);
+        },
+        lookupKeyBuilder(name) {
+            return keyBuilders.get(name);
+        },
+        lookupLoader(name) {
+            return loaders.get(name);
+        },
+    };
+}
+/** Go time.ParseDuration-compatible parser (ns/us/ms/s/m/h). */
+export function parseDuration(s) {
+    if (s === "" || s === "0")
+        return 0;
+    const re = /(-?\d+(?:\.\d+)?)(ns|us|µs|μs|ms|s|m|h)/g;
+    let total = 0;
+    let matched = 0;
+    let m;
+    const units = {
+        ns: 1e-6,
+        us: 0.001,
+        µs: 0.001,
+        μs: 0.001,
+        ms: 1,
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+    };
+    while ((m = re.exec(s)) !== null) {
+        matched += m[0].length;
+        const n = Number(m[1]);
+        const u = m[2];
+        total += n * (units[u] ?? 0);
+    }
+    if (matched !== s.length || Number.isNaN(total)) {
+        throw new Error(`${ErrInvalidConfig.message}: invalid ttl ${JSON.stringify(s)}`);
+    }
+    if (total < 0)
+        throw ErrNegativeTTL;
+    return total;
+}
+function optionalTTL(v) {
+    if (v == null)
+        return { set: false, ms: 0 };
+    if (typeof v !== "string") {
+        throw new Error(`${ErrInvalidConfig.message}: ttl must be a string duration`);
+    }
+    if (v === "")
+        return { set: false, ms: 0 };
+    return { set: true, ms: parseDuration(v) };
+}
+function schemaVersion(v) {
+    if (v == null || v === "") {
+        throw new Error(`${ErrInvalidConfig.message}: schema_version is required`);
+    }
+    if (typeof v !== "string") {
+        throw new Error(`${ErrInvalidConfig.message}: schema_version must be a string`);
+    }
+    return v;
+}
+function stringOptions(opts) {
+    if (opts == null)
+        return {};
+    if (typeof opts !== "object" || Array.isArray(opts)) {
+        throw new Error(`${ErrInvalidConfig.message}: options must be a map`);
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(opts)) {
+        if (typeof v !== "string") {
+            throw new Error(`${ErrInvalidConfig.message}: option ${JSON.stringify(k)} must be a string`);
+        }
+        out[k] = v;
+    }
+    return out;
+}
+async function buildLayer(rl) {
+    const driver = rl.driver;
+    if (typeof driver !== "string" || driver === "") {
+        throw new Error(`${ErrInvalidConfig.message}: driver must not be empty`);
+    }
+    const opts = stringOptions(rl.options);
+    if (driver === "memory") {
+        for (const k of Object.keys(opts)) {
+            throw new Error(`${ErrInvalidConfig.message}: unknown memory option ${JSON.stringify(k)}`);
+        }
+        return newMemoryStore();
+    }
+    if (driver === "firestore") {
+        const projectId = opts.project_id;
+        const collection = opts.collection;
+        for (const k of Object.keys(opts)) {
+            if (k !== "project_id" && k !== "collection") {
+                throw new Error(`${ErrInvalidConfig.message}: unknown firestore option ${JSON.stringify(k)}`);
+            }
+        }
+        return newFirestoreStore({ projectId, collection });
+    }
+    throw new Error(`${ErrInvalidConfig.message}: unknown driver ${JSON.stringify(driver)}`);
+}
+async function buildOneType(reg, rt) {
+    if (typeof rt.name !== "string" || rt.name === "") {
+        throw new Error(`${ErrInvalidConfig.message}: type name must not be empty`);
+    }
+    if (!Array.isArray(rt.layers) || rt.layers.length === 0) {
+        throw new Error(`${ErrInvalidConfig.message}: type ${JSON.stringify(rt.name)}: layers must not be empty`);
+    }
+    const kbName = rt.key_builder == null || rt.key_builder === ""
+        ? "default"
+        : typeof rt.key_builder === "string"
+            ? rt.key_builder
+            : null;
+    if (kbName == null) {
+        throw new Error(`${ErrInvalidConfig.message}: key_builder must be a string`);
+    }
+    const kb = reg.lookupKeyBuilder(kbName);
+    if (!kb) {
+        throw new Error(`${ErrInvalidConfig.message}: unknown key_builder ${JSON.stringify(kbName)}`);
+    }
+    let loader;
+    if (rt.loader != null && rt.loader !== "") {
+        if (typeof rt.loader !== "string") {
+            throw new Error(`${ErrInvalidConfig.message}: loader must be a string`);
+        }
+        const found = reg.lookupLoader(rt.loader);
+        if (!found) {
+            throw new Error(`${ErrInvalidConfig.message}: unknown loader ${JSON.stringify(rt.loader)}`);
+        }
+        loader = found;
+    }
+    const typeTTL = optionalTTL(rt.ttl);
+    const layers = [];
+    const ttls = [];
+    for (let i = 0; i < rt.layers.length; i++) {
+        const rl = rt.layers[i];
+        layers.push(await buildLayer(rl));
+        const layerTTL = optionalTTL(rl.ttl);
+        if (layerTTL.set)
+            ttls.push(layerTTL.ms);
+        else if (typeTTL.set)
+            ttls.push(typeTTL.ms);
+        else
+            ttls.push(0);
+    }
+    const b = define(rt.name).withLayers(...layers).withKeyBuilder(kb).withLayerTTLs(...ttls);
+    if (loader)
+        b.withLoader(loader);
+    return b.build();
+}
+async function buildTypes(reg, raw) {
+    const ver = schemaVersion(raw.schema_version);
+    if (ver !== SCHEMA_VERSION) {
+        throw new Error(`${ErrInvalidConfig.message}: unsupported schema_version ${JSON.stringify(ver)}`);
+    }
+    if (!Array.isArray(raw.types) || raw.types.length === 0) {
+        throw new Error(`${ErrInvalidConfig.message}: types must not be empty`);
+    }
+    const out = new Map();
+    for (const rt of raw.types) {
+        const name = typeof rt.name === "string" ? rt.name : "";
+        if (out.has(name)) {
+            throw new Error(`${ErrInvalidConfig.message}: duplicate type name ${JSON.stringify(name)}`);
+        }
+        const ct = await buildOneType(reg, rt);
+        out.set(ct.name(), ct);
+    }
+    return out;
+}
+export async function loadTypesYAML(reg, data) {
+    const text = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (e) {
+        throw new Error(`${ErrInvalidConfig.message}: yaml: ${e instanceof Error ? e.message : e}`);
+    }
+    return buildTypes(reg, raw ?? {});
+}
+export async function loadTypesJSON(reg, data) {
+    const text = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${ErrInvalidConfig.message}: json: ${e instanceof Error ? e.message : e}`);
+    }
+    return buildTypes(reg, raw ?? {});
+}
+export async function loadTypes(reg, filePath) {
+    const data = await fs.readFile(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".json")
+        return loadTypesJSON(reg, data);
+    if (ext === ".yaml" || ext === ".yml")
+        return loadTypesYAML(reg, data);
+    throw new Error(`${ErrInvalidConfig.message}: unsupported config extension ${JSON.stringify(ext)}`);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/driver/firestore.d.ts

@@ -0,0 +1,24 @@
+import { Firestore } from "@google-cloud/firestore";
+import { type DurationMs, type Entry, type Layer } from "../types.js";
+export type FirestoreOptions = {
+    projectId?: string;
+    collection?: string;
+};
+export declare class FirestoreStore implements Layer {
+    #private;
+    constructor(client: Firestore, collection: string);
+    static create(opts?: FirestoreOptions): Promise<FirestoreStore>;
+    close(): Promise<void>;
+    get(key: string, _signal?: AbortSignal): Promise<{
+        entry: Entry;
+        hit: boolean;
+    }>;
+    set(key: string, entry: Entry, ttl: DurationMs, _signal?: AbortSignal): Promise<void>;
+    delete(key: string, _signal?: AbortSignal): Promise<void>;
+    incr(key: string, _signal?: AbortSignal): Promise<number>;
+    purgeExact(logicalPrefix: string, _signal?: AbortSignal): Promise<void>;
+    /** Tests only. */
+    clearCollection(): Promise<void>;
+}
+export declare function newFirestoreStore(opts?: FirestoreOptions): Promise<FirestoreStore>;
+//# sourceMappingURL=firestore.d.ts.map

package/dist/driver/firestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore.d.ts","sourceRoot":"","sources":["../../src/driver/firestore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAqB,MAAM,yBAAyB,CAAC;AAEvE,OAAO,EACL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,KAAK,EAOX,MAAM,aAAa,CAAC;AAIrB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAQF,qBAAa,cAAe,YAAW,KAAK;;gBAI9B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM;WAKpC,MAAM,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAOnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;IA2BhF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IASzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAiDzD,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7E,kBAAkB;IACZ,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC;AAED,wBAAsB,iBAAiB,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAExF"}

package/dist/driver/firestore.js

@@ -0,0 +1,191 @@
+import { Firestore } from "@google-cloud/firestore";
+import { ErrEmptyKey, ErrIncrOverflow, ErrNegativeTTL, ErrNotInteger, isExpired, isVersionDataKey, } from "../types.js";
+const defaultCollection = "sscachian";
+export class FirestoreStore {
+    #client;
+    #collection;
+    constructor(client, collection) {
+        this.#client = client;
+        this.#collection = collection;
+    }
+    static async create(opts = {}) {
+        const projectId = opts.projectId || "ss-cachian-dev";
+        const collection = opts.collection || defaultCollection;
+        const client = new Firestore({ projectId });
+        return new FirestoreStore(client, collection);
+    }
+    async close() {
+        await this.#client.terminate();
+    }
+    #doc(key) {
+        return this.#client.collection(this.#collection).doc(key);
+    }
+    async get(key, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        const snap = await this.#doc(key).get();
+        if (!snap.exists)
+            return { entry: emptyEntry(), hit: false };
+        const f = snap.data();
+        const expiresAt = toDateOrNull(f.expires_at);
+        if (isExpired(expiresAt))
+            return { entry: emptyEntry(), hit: false };
+        let val = null;
+        const raw = f.value;
+        if (raw != null && (typeof raw === "string" ? raw.length > 0 : raw.length > 0)) {
+            const text = typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
+            try {
+                val = JSON.parse(text);
+            }
+            catch {
+                throw new Error("sscachian/firestore: invalid JSON value");
+            }
+        }
+        return {
+            entry: {
+                value: val,
+                createdAt: toDateOrNull(f.created_at) ?? new Date(0),
+                expiresAt,
+            },
+            hit: true,
+        };
+    }
+    async set(key, entry, ttl, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        if (ttl < 0)
+            throw ErrNegativeTTL;
+        const now = new Date();
+        let createdAt = entry.createdAt.getTime() === 0 ? now : entry.createdAt;
+        let expiresAt = entry.expiresAt;
+        if (ttl > 0) {
+            expiresAt = new Date(now.getTime() + ttl);
+        }
+        let raw;
+        try {
+            raw = JSON.stringify(entry.value === undefined ? null : entry.value);
+        }
+        catch (err) {
+            throw new Error(`sscachian/firestore: marshal value: ${String(err)}`);
+        }
+        const data = {
+            value: Buffer.from(raw, "utf8"),
+            created_at: createdAt,
+            expires_at: expiresAt ?? new Date(0),
+        };
+        await this.#doc(key).set(data);
+    }
+    async delete(key, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        try {
+            await this.#doc(key).delete();
+        }
+        catch {
+            // missing is ok
+        }
+    }
+    async incr(key, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        const ref = this.#doc(key);
+        let last;
+        for (let attempt = 0; attempt < 8; attempt++) {
+            try {
+                const out = await this.#client.runTransaction(async (tx) => {
+                    const snap = await tx.get(ref);
+                    let n = 0;
+                    if (snap.exists) {
+                        const f = snap.data();
+                        const text = typeof f.value === "string"
+                            ? f.value
+                            : Buffer.from(f.value ?? []).toString("utf8");
+                        let val;
+                        try {
+                            val = JSON.parse(text);
+                        }
+                        catch {
+                            throw ErrNotInteger;
+                        }
+                        n = asIncrInt(val);
+                    }
+                    if (n >= Number.MAX_SAFE_INTEGER)
+                        throw ErrIncrOverflow;
+                    n += 1;
+                    const raw = JSON.stringify(n);
+                    tx.set(ref, {
+                        value: Buffer.from(raw, "utf8"),
+                        created_at: new Date(),
+                        expires_at: new Date(0),
+                    });
+                    return n;
+                });
+                return out;
+            }
+            catch (err) {
+                last = err;
+                if (err === ErrNotInteger || err === ErrIncrOverflow)
+                    throw err;
+                const code = err.code;
+                const aborted = code === 10 ||
+                    code === "ABORTED" ||
+                    (err instanceof Error && /ABORTED|aborted/i.test(err.message));
+                if (!aborted)
+                    throw err;
+                await sleep((attempt + 1) * 5);
+            }
+        }
+        throw last instanceof Error ? last : new Error(String(last));
+    }
+    async purgeExact(logicalPrefix, _signal) {
+        if (logicalPrefix === "")
+            throw ErrEmptyKey;
+        const snap = await this.#client.collection(this.#collection).get();
+        for (const doc of snap.docs) {
+            if (!isVersionDataKey(logicalPrefix, doc.id))
+                continue;
+            await doc.ref.delete();
+        }
+    }
+    /** Tests only. */
+    async clearCollection() {
+        const snap = await this.#client.collection(this.#collection).get();
+        for (const doc of snap.docs) {
+            await doc.ref.delete();
+        }
+    }
+}
+export async function newFirestoreStore(opts) {
+    return FirestoreStore.create(opts);
+}
+function emptyEntry() {
+    return { value: undefined, createdAt: new Date(0), expiresAt: null };
+}
+function toDateOrNull(v) {
+    if (v == null)
+        return null;
+    if (v instanceof Date) {
+        if (v.getTime() === 0)
+            return null;
+        return v;
+    }
+    if (typeof v === "object" && v !== null && "toDate" in v && typeof v.toDate === "function") {
+        const d = v.toDate();
+        if (d.getTime() === 0)
+            return null;
+        return d;
+    }
+    return null;
+}
+function asIncrInt(v) {
+    if (typeof v === "number") {
+        if (!Number.isInteger(v))
+            throw ErrNotInteger;
+        return v;
+    }
+    throw ErrNotInteger;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=firestore.js.map

package/dist/driver/firestore.js.map

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

package/dist/driver/memory.d.ts

@@ -0,0 +1,17 @@
+import { type DurationMs, type Entry, type Layer } from "../types.js";
+/** Process-local Layer (mutex via sync Map ops on event loop). */
+export declare class MemoryStore implements Layer {
+    #private;
+    /** Test helper: store arbitrary raw value. */
+    injectRaw(key: string, v: unknown): void;
+    get(key: string, _signal?: AbortSignal): Promise<{
+        entry: Entry;
+        hit: boolean;
+    }>;
+    set(key: string, entry: Entry, ttl: DurationMs, _signal?: AbortSignal): Promise<void>;
+    delete(key: string, _signal?: AbortSignal): Promise<void>;
+    incr(key: string, _signal?: AbortSignal): Promise<number>;
+    purgeExact(logicalPrefix: string, _signal?: AbortSignal): Promise<void>;
+}
+export declare function newMemoryStore(): MemoryStore;
+//# sourceMappingURL=memory.d.ts.map

package/dist/driver/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/driver/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,KAAK,EAOX,MAAM,aAAa,CAAC;AAErB,kEAAkE;AAClE,qBAAa,WAAY,YAAW,KAAK;;IAGvC,8CAA8C;IAC9C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAG,IAAI;IAIlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;IAehF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAerF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAczD,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAM9E;AAED,wBAAgB,cAAc,IAAI,WAAW,CAE5C"}

package/dist/driver/memory.js

@@ -0,0 +1,94 @@
+import { ErrEmptyKey, ErrIncrOverflow, ErrNegativeTTL, ErrNotInteger, isExpired, isVersionDataKey, } from "../types.js";
+/** Process-local Layer (mutex via sync Map ops on event loop). */
+export class MemoryStore {
+    #m = new Map();
+    /** Test helper: store arbitrary raw value. */
+    injectRaw(key, v) {
+        this.#m.set(key, v);
+    }
+    async get(key, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        const raw = this.#m.get(key);
+        if (raw === undefined)
+            return { entry: emptyEntry(), hit: false };
+        if (!isEntry(raw)) {
+            this.#m.delete(key);
+            return { entry: emptyEntry(), hit: false };
+        }
+        if (isExpired(raw.expiresAt)) {
+            this.#m.delete(key);
+            return { entry: emptyEntry(), hit: false };
+        }
+        return { entry: { ...raw }, hit: true };
+    }
+    async set(key, entry, ttl, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        if (ttl < 0)
+            throw ErrNegativeTTL;
+        const now = new Date();
+        const stored = {
+            value: entry.value,
+            createdAt: entry.createdAt.getTime() === 0 ? now : new Date(entry.createdAt),
+            expiresAt: entry.expiresAt,
+        };
+        if (ttl > 0) {
+            stored.expiresAt = new Date(now.getTime() + ttl);
+        }
+        this.#m.set(key, stored);
+    }
+    async delete(key, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        this.#m.delete(key);
+    }
+    async incr(key, _signal) {
+        if (key === "")
+            throw ErrEmptyKey;
+        const raw = this.#m.get(key);
+        let n = 0;
+        if (raw !== undefined) {
+            if (!isEntry(raw))
+                throw ErrNotInteger;
+            n = asIncrInt(raw.value);
+        }
+        if (n >= Number.MAX_SAFE_INTEGER)
+            throw ErrIncrOverflow;
+        n += 1;
+        this.#m.set(key, { value: n, createdAt: new Date(), expiresAt: null });
+        return n;
+    }
+    async purgeExact(logicalPrefix, _signal) {
+        if (logicalPrefix === "")
+            throw ErrEmptyKey;
+        for (const k of [...this.#m.keys()]) {
+            if (isVersionDataKey(logicalPrefix, k))
+                this.#m.delete(k);
+        }
+    }
+}
+export function newMemoryStore() {
+    return new MemoryStore();
+}
+function emptyEntry() {
+    return { value: undefined, createdAt: new Date(0), expiresAt: null };
+}
+function isEntry(v) {
+    if (v == null || typeof v !== "object")
+        return false;
+    const o = v;
+    return "value" in o && "createdAt" in o && "expiresAt" in o;
+}
+function asIncrInt(v) {
+    if (typeof v === "number" && Number.isInteger(v))
+        return v;
+    if (typeof v === "bigint") {
+        const n = Number(v);
+        if (!Number.isSafeInteger(n))
+            throw ErrNotInteger;
+        return n;
+    }
+    throw ErrNotInteger;
+}
+//# sourceMappingURL=memory.js.map

package/dist/driver/memory.js.map

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

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 /**
- * Placeholder entry for the Node.js / TypeScript port.
- * Semantics follow the Go package at go/sscachian (v0.7.0 PoC).
+ * @b4moss/ss-cachian — Node.js / TypeScript port of ss-cachian (Go v0.7.0+ parity).
  */
 export declare const SSCACHIAN_RUNTIME: "node";
-export declare function placeholder(): string;
+export { ErrEmptyKey, ErrNegativeTTL, ErrNotInteger, ErrIncrOverflow, ErrNoLayer, ErrNoKeyBuilder, ErrInvalidVersion, ErrNoLoader, ErrTypeMismatch, ErrInvalidContext, ErrCorruptVersion, ErrInvalidLayerIndex, ErrInvalidConfig, SscachianError, isVersionDataKey, defaultKeyBuilder, type Entry, type Layer, type DurationMs, type KeyContext, type KeyBuilder, type Loader, type TypeGuard, } from "./types.js";
+export { define, Builder, CacheType } from "./cache.js";
+export { MemoryStore, newMemoryStore } from "./driver/memory.js";
+export { FirestoreStore, newFirestoreStore, type FirestoreOptions, } from "./driver/firestore.js";
+export { createRegistry, loadTypes, loadTypesYAML, loadTypesJSON, parseDuration, type Registry, } from "./config.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAG,MAAe,CAAC;AAEjD,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,iBAAiB,EAAG,MAAe,CAAC;AAEjD,OAAO,EACL,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,9 +1,10 @@
 /**
- * Placeholder entry for the Node.js / TypeScript port.
- * Semantics follow the Go package at go/sscachian (v0.7.0 PoC).
+ * @b4moss/ss-cachian — Node.js / TypeScript port of ss-cachian (Go v0.7.0+ parity).
  */
 export const SSCACHIAN_RUNTIME = "node";
-export function placeholder() {
-    return "ss-cachian node port — not yet implemented";
-}
+export { ErrEmptyKey, ErrNegativeTTL, ErrNotInteger, ErrIncrOverflow, ErrNoLayer, ErrNoKeyBuilder, ErrInvalidVersion, ErrNoLoader, ErrTypeMismatch, ErrInvalidContext, ErrCorruptVersion, ErrInvalidLayerIndex, ErrInvalidConfig, SscachianError, isVersionDataKey, defaultKeyBuilder, } from "./types.js";
+export { define, Builder, CacheType } from "./cache.js";
+export { MemoryStore, newMemoryStore } from "./driver/memory.js";
+export { FirestoreStore, newFirestoreStore, } from "./driver/firestore.js";
+export { createRegistry, loadTypes, loadTypesYAML, loadTypesJSON, parseDuration, } from "./config.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAe,CAAC;AAEjD,MAAM,UAAU,WAAW;IACzB,OAAO,4CAA4C,CAAC;AACtD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAe,CAAC;AAEjD,OAAO,EACL,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAQlB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,iBAAiB,GAElB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,aAAa,GAEd,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+/** Shared errors and Layer contract (Go parity). */
+export declare class SscachianError extends Error {
+    constructor(message: string);
+}
+export declare const ErrEmptyKey: SscachianError;
+export declare const ErrNegativeTTL: SscachianError;
+export declare const ErrNotInteger: SscachianError;
+export declare const ErrIncrOverflow: SscachianError;
+export declare const ErrNoLayer: SscachianError;
+export declare const ErrNoKeyBuilder: SscachianError;
+export declare const ErrInvalidVersion: SscachianError;
+export declare const ErrNoLoader: SscachianError;
+export declare const ErrTypeMismatch: SscachianError;
+export declare const ErrInvalidContext: SscachianError;
+export declare const ErrCorruptVersion: SscachianError;
+export declare const ErrInvalidLayerIndex: SscachianError;
+export declare const ErrInvalidConfig: SscachianError;
+/** On-Layer storage wrapper. */
+export type Entry = {
+    value: unknown;
+    createdAt: Date;
+    /** Invalid / epoch 0 means no expiry (Go zero time). */
+    expiresAt: Date | null;
+};
+export declare function noExpiry(): null;
+export declare function isExpired(expiresAt: Date | null, now?: Date): boolean;
+/** TTL in milliseconds. 0 = no expiry from TTL arg. */
+export type DurationMs = number;
+export type Layer = {
+    get(key: string, signal?: AbortSignal): Promise<{
+        entry: Entry;
+        hit: boolean;
+    }>;
+    set(key: string, entry: Entry, ttl: DurationMs, signal?: AbortSignal): Promise<void>;
+    delete(key: string, signal?: AbortSignal): Promise<void>;
+    incr(key: string, signal?: AbortSignal): Promise<number>;
+    purgeExact(logicalPrefix: string, signal?: AbortSignal): Promise<void>;
+};
+/** True when key is `{logicalPrefix}:{digits}` (digits non-empty). */
+export declare function isVersionDataKey(logicalPrefix: string, key: string): boolean;
+export type KeyContext = {
+    appSlug: string;
+    tenantId: string;
+    queryType: string;
+};
+export type KeyBuilder = (kc: KeyContext, signal?: AbortSignal) => Promise<string> | string;
+export type Loader<T> = (kc: KeyContext, signal?: AbortSignal) => Promise<T>;
+export type TypeGuard<T> = (v: unknown) => v is T;
+export declare function defaultKeyBuilder(kc: KeyContext): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,WAAW,gBAA6C,CAAC;AACtE,eAAO,MAAM,cAAc,gBAAgD,CAAC;AAC5E,eAAO,MAAM,aAAa,gBAA2D,CAAC;AACtF,eAAO,MAAM,eAAe,gBAAiD,CAAC;AAC9E,eAAO,MAAM,UAAU,gBAAwD,CAAC;AAChF,eAAO,MAAM,eAAe,gBAA8D,CAAC;AAC3F,eAAO,MAAM,iBAAiB,gBAAwD,CAAC;AACvF,eAAO,MAAM,WAAW,gBAAyD,CAAC;AAClF,eAAO,MAAM,eAAe,gBAA8D,CAAC;AAC3F,eAAO,MAAM,iBAAiB,gBAAuD,CAAC;AACtF,eAAO,MAAM,iBAAiB,gBAAiE,CAAC;AAChG,eAAO,MAAM,oBAAoB,gBAAuD,CAAC;AACzF,eAAO,MAAM,gBAAgB,gBAAkD,CAAC;AAEhF,gCAAgC;AAChC,MAAM,MAAM,KAAK,GAAG;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,wDAAwD;IACxD,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,wBAAgB,QAAQ,IAAI,IAAI,CAE/B;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,OAAa,GAAG,OAAO,CAI3E;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,MAAM,MAAM,KAAK,GAAG;IAClB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE,CAAC;AAEF,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAU5E;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAC5F,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAC7E,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;AAElD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAKxD"}

package/dist/types.js

@@ -0,0 +1,53 @@
+/** Shared errors and Layer contract (Go parity). */
+export class SscachianError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SscachianError";
+    }
+}
+export const ErrEmptyKey = new SscachianError("sscachian: empty key");
+export const ErrNegativeTTL = new SscachianError("sscachian: negative TTL");
+export const ErrNotInteger = new SscachianError("sscachian: value is not an integer");
+export const ErrIncrOverflow = new SscachianError("sscachian: incr overflow");
+export const ErrNoLayer = new SscachianError("sscachian: no layers configured");
+export const ErrNoKeyBuilder = new SscachianError("sscachian: key builder not configured");
+export const ErrInvalidVersion = new SscachianError("sscachian: version must be >= 1");
+export const ErrNoLoader = new SscachianError("sscachian: loader not configured");
+export const ErrTypeMismatch = new SscachianError("sscachian: cached value type mismatch");
+export const ErrInvalidContext = new SscachianError("sscachian: invalid key context");
+export const ErrCorruptVersion = new SscachianError("sscachian: corrupt current-version value");
+export const ErrInvalidLayerIndex = new SscachianError("sscachian: invalid layer index");
+export const ErrInvalidConfig = new SscachianError("sscachian: invalid config");
+export function noExpiry() {
+    return null;
+}
+export function isExpired(expiresAt, now = new Date()) {
+    if (expiresAt == null)
+        return false;
+    if (expiresAt.getTime() === 0)
+        return false;
+    return !(expiresAt.getTime() > now.getTime());
+}
+/** True when key is `{logicalPrefix}:{digits}` (digits non-empty). */
+export function isVersionDataKey(logicalPrefix, key) {
+    if (logicalPrefix === "" || key === "")
+        return false;
+    const want = `${logicalPrefix}:`;
+    if (!key.startsWith(want))
+        return false;
+    const rest = key.slice(want.length);
+    if (rest === "")
+        return false;
+    for (const ch of rest) {
+        if (ch < "0" || ch > "9")
+            return false;
+    }
+    return true;
+}
+export function defaultKeyBuilder(kc) {
+    if (!kc.appSlug || !kc.tenantId || !kc.queryType) {
+        throw ErrInvalidContext;
+    }
+    return `${kc.appSlug}:cache:${kc.tenantId}:${kc.queryType}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@b4moss/ss-cachian",
-  "version": "0.7.0",
-  "description": "Server-side cache strategy library (TypeScript/JavaScript). Go PoC is complete; Node port is in progress.",
+  "version": "0.9.0",
+  "description": "Server-side cache strategy library (TypeScript/JavaScript). Config-driven Cache Types (v0.9.0) with Go parity.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -23,7 +23,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test dist/**/*.test.js",
+    "test": "rm -rf dist && npm run build && node --test 'dist/**/*.test.js'",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -49,7 +49,11 @@
     "versioned-cache"
   ],
   "devDependencies": {
-    "@types/node": "^22.13.10",
+    "@types/node": "^22.20.4",
     "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "@google-cloud/firestore": "^7.11.6",
+    "yaml": "^2.7.0"
   }
 }