@warlock.js/cache 4.0.171 → 4.1.1

package/esm/tagged-scoped-cache.d.mts

@@ -0,0 +1,111 @@
+import { CacheKey, CacheSetOptions, CacheTtl, RememberOptions, TaggedScopedCacheContract } from "./types.mjs";
+import { ScopedCache } from "./scoped-cache.mjs";
+
+//#region ../../@warlock.js/cache/src/tagged-scoped-cache.d.ts
+/**
+ * One-shot tagged write handle on top of a {@link ScopedCache}.
+ *
+ * **Role.** Returned by `scope.tags([...])`. Adds a fixed list of tags to
+ * every write produced through this handle, on top of any tags the parent
+ * scope already contributes. Stateless except for the captured tag list.
+ *
+ * **Responsibility.**
+ * - Owns: appending the handle's tags to writes, delegating tag-index
+ *   bookkeeping for `setNX` (which lacks an inline `tags` knob on the driver
+ *   contract), and computing the union for `invalidate()` calls.
+ * - Does NOT own: storage, prefix-prepending (delegated to the scope),
+ *   default `ttl` (delegated to the scope), or any kind of long-lived state.
+ *
+ * Tags compose additively: scope tags + handle tags + per-call tags, all
+ * unioned and deduped. The handle never replaces scope tags — `invalidate()`
+ * always sees the full union.
+ *
+ * @example
+ * // Inside application code — scope provides the per-user tag automatically:
+ * const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
+ *
+ * await feed.tags(["unread"]).set("messages.1", message);
+ * // → tagged with [user.<id>, unread]
+ *
+ * await feed.tags(["unread"]).invalidate();
+ * // → wipes everything tagged with user.<id> OR unread.
+ */
+declare class TaggedScopedCache implements TaggedScopedCacheContract {
+  /**
+   * The {@link ScopedCache} this handle delegates to. Held by reference so
+   * scope-default changes (none today, but the option is preserved for the
+   * future) are visible without rebuilding the handle.
+   */
+  protected readonly scope: ScopedCache;
+  /**
+   * Tags this handle contributes to every write. Cloned at the call site so
+   * later mutation of the input array doesn't leak in.
+   */
+  protected readonly handleTags: string[];
+  /**
+   * Build a tagged handle. Constructed via `scope.tags([...])` — users never
+   * call this directly.
+   */
+  constructor(scope: ScopedCache, handleTags: string[]);
+  /**
+   * Write the scoped key with the handle's tags appended to whatever the
+   * caller passed. Scope-level tags are added on top by the scope itself.
+   */
+  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * Read the scoped key. Tags don't affect reads — pass-through.
+   */
+  get<T = any>(key: CacheKey): Promise<T | null>;
+  /**
+   * Check presence of the scoped key.
+   */
+  has(key: CacheKey): Promise<boolean>;
+  /**
+   * Remove the scoped key. The tag-index entry will eventually be cleaned up
+   * by `invalidate()`; we don't proactively rewrite it here for cost reasons.
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * Read-and-remove the scoped key.
+   */
+  pull<T = any>(key: CacheKey): Promise<T | null>;
+  /**
+   * Permanent write with handle tags applied. Bypasses both the scope's and
+   * the caller's TTL (forever means forever) — only tags get injected.
+   */
+  forever<T = any>(key: CacheKey, value: T): Promise<T>;
+  /**
+   * Atomic create-or-skip with the handle's tags applied on success. The
+   * driver contract has no inline `tags` knob on `setNX`, so we register the
+   * tag relationship manually after a successful write.
+   */
+  setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;
+  /**
+   * Read-or-compute with handle tags appended on the cache-miss write.
+   */
+  remember<T = any>(key: CacheKey, ttlOrOptions: CacheTtl | RememberOptions, callback: () => Promise<T>): Promise<T>;
+  /**
+   * Atomic counter increment on the scoped key. Tags aren't applied to
+   * subsequent increments — they're attached at first-write time.
+   */
+  increment(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * Atomic counter decrement on the scoped key. See {@link increment}.
+   */
+  decrement(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * Wipe every entry tagged with the union of (scope tags + handle tags).
+   * Tags are global across the package, so this reaches outside the scope's
+   * prefix when scope tags are also used elsewhere.
+   */
+  invalidate(): Promise<void>;
+  /**
+   * Compute the source-side key the same way `ScopedCache.scopedKey` does —
+   * needed for `setNX`, where we have to register the tag relationship by
+   * hand because the driver contract doesn't accept inline tags there.
+   */
+  protected buildScopedKey(key: CacheKey): string;
+}
+//#endregion
+export { TaggedScopedCache };
+//# sourceMappingURL=tagged-scoped-cache.d.mts.map

package/esm/tagged-scoped-cache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagged-scoped-cache.d.mts","names":[],"sources":["../../../../../@warlock.js/cache/src/tagged-scoped-cache.ts"],"mappings":";;;;;;AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,iBAAA,YAA6B,yBAAA;EA+Gb;;;;;EAAA,mBAzGR,KAAA,EAAO,WAAA;EAwHuB;;;;EAAA,mBAlH9B,UAAA;EAZqB;;;;cAkBrB,KAAA,EAAO,WAAA,EAAa,UAAA;EAZb;;;;EAqBnB,GAAA,CACL,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;EAboC;;;EAsBhC,GAAA,SAAA,CAAa,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,CAAA;EAX1C;;;EAkBK,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EAhBxB;;;;EAwBI,MAAA,CAAO,GAAA,EAAK,QAAA,GAAW,OAAA;EAfM;;;EAsB7B,IAAA,SAAA,CAAc,GAAA,EAAK,QAAA,GAAW,OAAA,CAAQ,CAAA;EAflC;;;;EAuBJ,OAAA,SAAA,CAAiB,GAAA,EAAK,QAAA,EAAU,KAAA,EAAO,CAAA,GAAI,OAAA,CAAQ,CAAA;EAf5B;;;;;EA2BjB,KAAA,CAAM,GAAA,EAAK,QAAA,EAAU,KAAA,OAAY,GAAA,YAAe,OAAA;EApBhB;;;EA+CtC,QAAA,SAAA,CACL,GAAA,EAAK,QAAA,EACL,YAAA,EAAc,QAAA,GAAW,eAAA,EACzB,QAAA,QAAgB,OAAA,CAAQ,CAAA,IACvB,OAAA,CAAQ,CAAA;EA3Ca;;;;EAwDjB,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAiB,OAAA;EA5CpC;;;EAmDN,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAiB,OAAA;EAnDH;;;;;EA4DjC,UAAA,CAAA,GAAc,OAAA;EA/BX;;;;;EAAA,UA8CN,cAAA,CAAe,GAAA,EAAK,QAAA;AAAA"}

package/esm/tagged-scoped-cache.mjs

@@ -0,0 +1,142 @@
+import { injectTags, mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey } from "./utils.mjs";
+
+//#region ../../@warlock.js/cache/src/tagged-scoped-cache.ts
+/**
+* One-shot tagged write handle on top of a {@link ScopedCache}.
+*
+* **Role.** Returned by `scope.tags([...])`. Adds a fixed list of tags to
+* every write produced through this handle, on top of any tags the parent
+* scope already contributes. Stateless except for the captured tag list.
+*
+* **Responsibility.**
+* - Owns: appending the handle's tags to writes, delegating tag-index
+*   bookkeeping for `setNX` (which lacks an inline `tags` knob on the driver
+*   contract), and computing the union for `invalidate()` calls.
+* - Does NOT own: storage, prefix-prepending (delegated to the scope),
+*   default `ttl` (delegated to the scope), or any kind of long-lived state.
+*
+* Tags compose additively: scope tags + handle tags + per-call tags, all
+* unioned and deduped. The handle never replaces scope tags — `invalidate()`
+* always sees the full union.
+*
+* @example
+* // Inside application code — scope provides the per-user tag automatically:
+* const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });
+*
+* await feed.tags(["unread"]).set("messages.1", message);
+* // → tagged with [user.<id>, unread]
+*
+* await feed.tags(["unread"]).invalidate();
+* // → wipes everything tagged with user.<id> OR unread.
+*/
+var TaggedScopedCache = class {
+	/**
+	* Build a tagged handle. Constructed via `scope.tags([...])` — users never
+	* call this directly.
+	*/
+	constructor(scope, handleTags) {
+		this.scope = scope;
+		this.handleTags = [...handleTags];
+	}
+	/**
+	* Write the scoped key with the handle's tags appended to whatever the
+	* caller passed. Scope-level tags are added on top by the scope itself.
+	*/
+	set(key, value, ttlOrOptions) {
+		const options = injectTags(normalizeToOptions(ttlOrOptions), this.handleTags);
+		return this.scope.set(key, value, options);
+	}
+	/**
+	* Read the scoped key. Tags don't affect reads — pass-through.
+	*/
+	get(key) {
+		return this.scope.get(key);
+	}
+	/**
+	* Check presence of the scoped key.
+	*/
+	has(key) {
+		return this.scope.has(key);
+	}
+	/**
+	* Remove the scoped key. The tag-index entry will eventually be cleaned up
+	* by `invalidate()`; we don't proactively rewrite it here for cost reasons.
+	*/
+	remove(key) {
+		return this.scope.remove(key);
+	}
+	/**
+	* Read-and-remove the scoped key.
+	*/
+	pull(key) {
+		return this.scope.pull(key);
+	}
+	/**
+	* Permanent write with handle tags applied. Bypasses both the scope's and
+	* the caller's TTL (forever means forever) — only tags get injected.
+	*/
+	forever(key, value) {
+		return this.scope.set(key, value, {
+			ttl: Infinity,
+			tags: this.handleTags
+		});
+	}
+	/**
+	* Atomic create-or-skip with the handle's tags applied on success. The
+	* driver contract has no inline `tags` knob on `setNX`, so we register the
+	* tag relationship manually after a successful write.
+	*/
+	async setNX(key, value, ttl) {
+		if (!await this.scope.setNX(key, value, ttl)) return false;
+		const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);
+		if (!allTags || allTags.length === 0) return true;
+		const scopedKey = this.buildScopedKey(key);
+		const parsedKey = this.scope.source.parseKey(scopedKey);
+		await this.scope.source.tags(allTags).storeTagRelationship(parsedKey);
+		return true;
+	}
+	/**
+	* Read-or-compute with handle tags appended on the cache-miss write.
+	*/
+	remember(key, ttlOrOptions, callback) {
+		const options = injectTags(normalizeToRememberOptions(ttlOrOptions), this.handleTags);
+		return this.scope.remember(key, options, callback);
+	}
+	/**
+	* Atomic counter increment on the scoped key. Tags aren't applied to
+	* subsequent increments — they're attached at first-write time.
+	*/
+	increment(key, value) {
+		return this.scope.increment(key, value);
+	}
+	/**
+	* Atomic counter decrement on the scoped key. See {@link increment}.
+	*/
+	decrement(key, value) {
+		return this.scope.decrement(key, value);
+	}
+	/**
+	* Wipe every entry tagged with the union of (scope tags + handle tags).
+	* Tags are global across the package, so this reaches outside the scope's
+	* prefix when scope tags are also used elsewhere.
+	*/
+	async invalidate() {
+		const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);
+		if (!allTags || allTags.length === 0) return;
+		await this.scope.source.tags(allTags).invalidate();
+	}
+	/**
+	* Compute the source-side key the same way `ScopedCache.scopedKey` does —
+	* needed for `setNX`, where we have to register the tag relationship by
+	* hand because the driver contract doesn't accept inline tags there.
+	*/
+	buildScopedKey(key) {
+		const keyString = typeof key === "string" ? key : parseCacheKey(key);
+		if (!keyString) return this.scope.prefix;
+		return `${this.scope.prefix}.${keyString}`;
+	}
+};
+
+//#endregion
+export { TaggedScopedCache };
+//# sourceMappingURL=tagged-scoped-cache.mjs.map

package/esm/tagged-scoped-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagged-scoped-cache.mjs","names":[],"sources":["../../../../../@warlock.js/cache/src/tagged-scoped-cache.ts"],"sourcesContent":["import type { ScopedCache } from \"./scoped-cache\";\nimport type {\n  CacheKey,\n  CacheSetOptions,\n  CacheTtl,\n  RememberOptions,\n  TaggedScopedCacheContract,\n} from \"./types\";\nimport {\n  injectTags,\n  mergeTagSets,\n  normalizeToOptions,\n  normalizeToRememberOptions,\n  parseCacheKey,\n} from \"./utils\";\n\n/**\n * One-shot tagged write handle on top of a {@link ScopedCache}.\n *\n * **Role.** Returned by `scope.tags([...])`. Adds a fixed list of tags to\n * every write produced through this handle, on top of any tags the parent\n * scope already contributes. Stateless except for the captured tag list.\n *\n * **Responsibility.**\n * - Owns: appending the handle's tags to writes, delegating tag-index\n *   bookkeeping for `setNX` (which lacks an inline `tags` knob on the driver\n *   contract), and computing the union for `invalidate()` calls.\n * - Does NOT own: storage, prefix-prepending (delegated to the scope),\n *   default `ttl` (delegated to the scope), or any kind of long-lived state.\n *\n * Tags compose additively: scope tags + handle tags + per-call tags, all\n * unioned and deduped. The handle never replaces scope tags — `invalidate()`\n * always sees the full union.\n *\n * @example\n * // Inside application code — scope provides the per-user tag automatically:\n * const feed = cache.namespace(`feed.${userId}`, { tags: [`user.${userId}`] });\n *\n * await feed.tags([\"unread\"]).set(\"messages.1\", message);\n * // → tagged with [user.<id>, unread]\n *\n * await feed.tags([\"unread\"]).invalidate();\n * // → wipes everything tagged with user.<id> OR unread.\n */\nexport class TaggedScopedCache implements TaggedScopedCacheContract {\n  /**\n   * The {@link ScopedCache} this handle delegates to. Held by reference so\n   * scope-default changes (none today, but the option is preserved for the\n   * future) are visible without rebuilding the handle.\n   */\n  protected readonly scope: ScopedCache;\n\n  /**\n   * Tags this handle contributes to every write. Cloned at the call site so\n   * later mutation of the input array doesn't leak in.\n   */\n  protected readonly handleTags: string[];\n\n  /**\n   * Build a tagged handle. Constructed via `scope.tags([...])` — users never\n   * call this directly.\n   */\n  public constructor(scope: ScopedCache, handleTags: string[]) {\n    this.scope = scope;\n    this.handleTags = [...handleTags];\n  }\n\n  /**\n   * Write the scoped key with the handle's tags appended to whatever the\n   * caller passed. Scope-level tags are added on top by the scope itself.\n   */\n  public set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any> {\n    const options = injectTags(normalizeToOptions(ttlOrOptions), this.handleTags);\n\n    return this.scope.set(key, value, options);\n  }\n\n  /**\n   * Read the scoped key. Tags don't affect reads — pass-through.\n   */\n  public get<T = any>(key: CacheKey): Promise<T | null> {\n    return this.scope.get<T>(key);\n  }\n\n  /**\n   * Check presence of the scoped key.\n   */\n  public has(key: CacheKey): Promise<boolean> {\n    return this.scope.has(key);\n  }\n\n  /**\n   * Remove the scoped key. The tag-index entry will eventually be cleaned up\n   * by `invalidate()`; we don't proactively rewrite it here for cost reasons.\n   */\n  public remove(key: CacheKey): Promise<void> {\n    return this.scope.remove(key);\n  }\n\n  /**\n   * Read-and-remove the scoped key.\n   */\n  public pull<T = any>(key: CacheKey): Promise<T | null> {\n    return this.scope.pull<T>(key);\n  }\n\n  /**\n   * Permanent write with handle tags applied. Bypasses both the scope's and\n   * the caller's TTL (forever means forever) — only tags get injected.\n   */\n  public forever<T = any>(key: CacheKey, value: T): Promise<T> {\n    return this.scope.set(key, value, {\n      ttl: Infinity,\n      tags: this.handleTags,\n    }) as Promise<T>;\n  }\n\n  /**\n   * Atomic create-or-skip with the handle's tags applied on success. The\n   * driver contract has no inline `tags` knob on `setNX`, so we register the\n   * tag relationship manually after a successful write.\n   */\n  public async setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\n    const wasSet = await this.scope.setNX(key, value, ttl);\n\n    if (!wasSet) {\n      return false;\n    }\n\n    const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);\n\n    if (!allTags || allTags.length === 0) {\n      return true;\n    }\n\n    const scopedKey = this.buildScopedKey(key);\n    const parsedKey = this.scope.source.parseKey(scopedKey);\n    const tagged = this.scope.source.tags(allTags) as unknown as {\n      storeTagRelationship: (parsed: string) => Promise<void>;\n    };\n\n    await tagged.storeTagRelationship(parsedKey);\n\n    return true;\n  }\n\n  /**\n   * Read-or-compute with handle tags appended on the cache-miss write.\n   */\n  public remember<T = any>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    const options = injectTags(\n      normalizeToRememberOptions(ttlOrOptions),\n      this.handleTags,\n    );\n\n    return this.scope.remember<T>(key, options, callback);\n  }\n\n  /**\n   * Atomic counter increment on the scoped key. Tags aren't applied to\n   * subsequent increments — they're attached at first-write time.\n   */\n  public increment(key: CacheKey, value?: number): Promise<number> {\n    return this.scope.increment(key, value);\n  }\n\n  /**\n   * Atomic counter decrement on the scoped key. See {@link increment}.\n   */\n  public decrement(key: CacheKey, value?: number): Promise<number> {\n    return this.scope.decrement(key, value);\n  }\n\n  /**\n   * Wipe every entry tagged with the union of (scope tags + handle tags).\n   * Tags are global across the package, so this reaches outside the scope's\n   * prefix when scope tags are also used elsewhere.\n   */\n  public async invalidate(): Promise<void> {\n    const allTags = mergeTagSets(this.scope.defaults.tags, this.handleTags);\n\n    if (!allTags || allTags.length === 0) {\n      return;\n    }\n\n    await this.scope.source.tags(allTags).invalidate();\n  }\n\n  /**\n   * Compute the source-side key the same way `ScopedCache.scopedKey` does —\n   * needed for `setNX`, where we have to register the tag relationship by\n   * hand because the driver contract doesn't accept inline tags there.\n   */\n  protected buildScopedKey(key: CacheKey): string {\n    const keyString = typeof key === \"string\" ? key : parseCacheKey(key);\n\n    if (!keyString) {\n      return this.scope.prefix;\n    }\n\n    return `${this.scope.prefix}.${keyString}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,IAAa,oBAAb,MAAoE;;;;;CAkBlE,AAAO,YAAY,OAAoB,YAAsB;EAC3D,KAAK,QAAQ;EACb,KAAK,aAAa,CAAC,GAAG,UAAU;CAClC;;;;;CAMA,AAAO,IACL,KACA,OACA,cACc;EACd,MAAM,UAAU,WAAW,mBAAmB,YAAY,GAAG,KAAK,UAAU;EAE5E,OAAO,KAAK,MAAM,IAAI,KAAK,OAAO,OAAO;CAC3C;;;;CAKA,AAAO,IAAa,KAAkC;EACpD,OAAO,KAAK,MAAM,IAAO,GAAG;CAC9B;;;;CAKA,AAAO,IAAI,KAAiC;EAC1C,OAAO,KAAK,MAAM,IAAI,GAAG;CAC3B;;;;;CAMA,AAAO,OAAO,KAA8B;EAC1C,OAAO,KAAK,MAAM,OAAO,GAAG;CAC9B;;;;CAKA,AAAO,KAAc,KAAkC;EACrD,OAAO,KAAK,MAAM,KAAQ,GAAG;CAC/B;;;;;CAMA,AAAO,QAAiB,KAAe,OAAsB;EAC3D,OAAO,KAAK,MAAM,IAAI,KAAK,OAAO;GAChC,KAAK;GACL,MAAM,KAAK;EACb,CAAC;CACH;;;;;;CAOA,MAAa,MAAM,KAAe,OAAY,KAAgC;EAG5E,IAAI,CAAC,MAFgB,KAAK,MAAM,MAAM,KAAK,OAAO,GAAG,GAGnD,OAAO;EAGT,MAAM,UAAU,aAAa,KAAK,MAAM,SAAS,MAAM,KAAK,UAAU;EAEtE,IAAI,CAAC,WAAW,QAAQ,WAAW,GACjC,OAAO;EAGT,MAAM,YAAY,KAAK,eAAe,GAAG;EACzC,MAAM,YAAY,KAAK,MAAM,OAAO,SAAS,SAAS;EAKtD,MAJe,KAAK,MAAM,OAAO,KAAK,OAI3B,EAAE,qBAAqB,SAAS;EAE3C,OAAO;CACT;;;;CAKA,AAAO,SACL,KACA,cACA,UACY;EACZ,MAAM,UAAU,WACd,2BAA2B,YAAY,GACvC,KAAK,UACP;EAEA,OAAO,KAAK,MAAM,SAAY,KAAK,SAAS,QAAQ;CACtD;;;;;CAMA,AAAO,UAAU,KAAe,OAAiC;EAC/D,OAAO,KAAK,MAAM,UAAU,KAAK,KAAK;CACxC;;;;CAKA,AAAO,UAAU,KAAe,OAAiC;EAC/D,OAAO,KAAK,MAAM,UAAU,KAAK,KAAK;CACxC;;;;;;CAOA,MAAa,aAA4B;EACvC,MAAM,UAAU,aAAa,KAAK,MAAM,SAAS,MAAM,KAAK,UAAU;EAEtE,IAAI,CAAC,WAAW,QAAQ,WAAW,GACjC;EAGF,MAAM,KAAK,MAAM,OAAO,KAAK,OAAO,EAAE,WAAW;CACnD;;;;;;CAOA,AAAU,eAAe,KAAuB;EAC9C,MAAM,YAAY,OAAO,QAAQ,WAAW,MAAM,cAAc,GAAG;EAEnE,IAAI,CAAC,WACH,OAAO,KAAK,MAAM;EAGpB,OAAO,GAAG,KAAK,MAAM,OAAO,GAAG;CACjC;AACF"}