@managemint-solutions/sdk 0.35.0 → 0.36.0

package/README.md

@@ -416,29 +416,40 @@ that branch on one (the invoice-number retry on `23505`).
 ## Cache
 
 ```ts
-import { createTaggedCache } from '@managemint-solutions/sdk/cache';
-import { userMeCacheKey, userCacheTag, USER_ME_CACHE_TTL_SECONDS } from '@managemint-solutions/entities/users/cache';
+import { createCache, profileCacheKey } from '@managemint-solutions/sdk/cache';
+import { PROFILE_CACHE_TTL_SECONDS } from '@managemint-solutions/entities/users/cache';
+import { FEATURE_FLAGS_CACHE_KEY } from '@managemint-solutions/entities/feature-flags';
 
-const cache = createTaggedCache({ url: UPSTASH_REDIS_REST_URL, token: UPSTASH_REDIS_REST_TOKEN });
+const cache = createCache({ url: UPSTASH_REDIS_REST_URL, token: UPSTASH_REDIS_REST_TOKEN });
 
-await cache.set(userMeCacheKey(mmsId), profile, { ttl: USER_ME_CACHE_TTL_SECONDS, tags: [userCacheTag(mmsId)] });
-const hit = await cache.get<LoggedInUser>(userMeCacheKey(mmsId)); // null on a miss
-await cache.invalidateTag([userCacheTag(mmsId)]);
+// Profiles: one hash per organization, one field per member.
+await cache.setField(profileCacheKey(organizationId), mmsId, profile, PROFILE_CACHE_TTL_SECONDS);
+const hit = await cache.getField<LoggedInUser>(profileCacheKey(organizationId), mmsId); // null on a miss
+await cache.deleteField(profileCacheKey(organizationId), mmsId); // one member
+await cache.delete(profileCacheKey(organizationId));             // every member
+
+// Global values: plain strings with their own TTL.
+await cache.set(FEATURE_FLAGS_CACHE_KEY, flags, 86_400);
+const flags = await cache.get<FeatureFlags>(FEATURE_FLAGS_CACHE_KEY);
 ```
 
-A tag-aware key-value cache on Upstash Redis (REST), shared by the portal, which reads and
-writes each member's own `GET /users/me`, and the api, which only expires it after a write.
-Redis has no tags, so each tag is a set of the keys written under it, stored as `tag:<tag>`
-and expiring with its newest member: `set` is one pipeline (`SET … EX ttl`, then `SADD` and
-`EXPIRE` per tag), `invalidateTag` is two round trips (`SMEMBERS` per tag, then one `DEL` of the
-members and the sets). Values are JSON-serialised by the client; `get<T>` is the caller's
-promise about what was written, not a check.
+A small client on Upstash Redis (REST), shared by the portal, which reads and writes each
+member's own `GET /users/me` and reads the feature flags, and the api, which writes the flags
+and drops profile entries after a write. Two shapes, chosen so the data browser stays readable
+and nothing needs an index of its own: a **string** per global value, and a **hash per
+organization** for the profiles, so dropping a member is one field delete and dropping an
+organization is one key delete. `setField` is one pipeline (`HSET`, then `EXPIRE … NX`): the
+hash's TTL is set once, when it is first written, so an organization's whole cache re-reads
+once a day however busy it is. Every other call is one round trip. Values are JSON-serialised
+by the client; `get<T>` / `getField<T>` are the caller's promise about what was written, not a
+check.
 
 The client takes its URL and token as config — the SDK reads no environment variables — and
 retries once with a three-second timeout per request. It **throws** on a failed call: what a
 failure means is the caller's decision, and both callers today fail open (a miss on the portal,
-a Sentry report on the api). The key, tag and TTL contract for the profile entry lives in
-`@managemint-solutions/entities/users/cache`, so the tagging is one edit for both sides.
+a Sentry report on the api). The key prefix and TTL for the profile hash live in
+`@managemint-solutions/entities/users/cache` and the flags key in `entities/feature-flags`;
+`profileCacheKey` here is the one builder both sides use.
 
 ## NestJS
 

package/dist/cache/index.d.ts

@@ -1,41 +1,47 @@
 /**
- * A tag-aware key-value cache on Upstash Redis, shared by the portal (which reads and writes
- * profile entries) and the api (which only expires them).
+ * The Upstash Redis cache shared by the portal (which reads and writes profile entries and
+ * reads the feature flags) and the api (which writes the flags and deletes profile entries).
  *
- * Redis has no tags of its own, so each tag is a set of the keys written under it, stored as
- * `tag:<tag>`. Expiring a tag deletes every key in the set and the set itself. The sets expire
- * with the entries they hold, so an entry that simply ages out leaves nothing behind.
+ * Two shapes, chosen so the data browser stays readable and nothing needs an index of its own:
  *
- * Deliberately narrow: three calls and no knowledge of what is cached. The key, tag and TTL
- * contract for the one thing cached today lives in `@managemint-solutions/entities/users/cache`.
+ * - **A string per global value** - the feature flags - with its own TTL.
+ * - **A hash per organization** for the member profiles: one field per member, so dropping a
+ *   member is one field delete and dropping an organization is one key delete. The hash's
+ *   TTL is set once, when it is first written, so the whole organization re-reads once a day
+ *   however busy it is.
  *
  * Like every other client in the SDK it takes its configuration as an argument and reads no
  * environment variables. It throws on a failed call; the callers decide what a failure means,
  * and both of them fail open.
  */
-export type TaggedCacheConfig = {
+export type CacheConfig = {
     /** The database's REST URL, `https://<name>.upstash.io`. */
     url: string;
     /** The database's REST token. */
     token: string;
 };
-export type TaggedCacheSetOptions = {
-    /** Seconds until the entry expires on its own. */
-    ttl: number;
-    /** The tags a later `invalidateTag` may drop the entry under. */
-    tags?: string[];
-};
-export declare class TaggedCache {
+/** The hash that holds an organization's cached member profiles. */
+export declare const profileCacheKey: (organizationId: string) => string;
+export declare class Cache {
     private readonly redis;
-    constructor(config: TaggedCacheConfig);
+    constructor(config: CacheConfig);
     /**
-     * The entry under `key`, or null when there is none. The value is JSON-parsed by the
+     * The string under `key`, or null when there is none. The value is JSON-parsed by the
      * client; `T` is the caller's promise about what was written, not a check.
      */
     get<T>(key: string): Promise<T | null>;
-    /** Writes `value` under `key` for `ttl` seconds, and files the key under each tag. One round trip. */
-    set(key: string, value: unknown, { ttl, tags }: TaggedCacheSetOptions): Promise<void>;
-    /** Deletes every entry filed under any of `tags`, and the tag sets themselves. Two round trips. */
-    invalidateTag(tags: string[]): Promise<void>;
+    /** Writes `value` under `key` for `ttl` seconds. One round trip. */
+    set(key: string, value: unknown, ttl: number): Promise<void>;
+    /** Deletes `key` - a string or a whole hash. One round trip. */
+    delete(key: string): Promise<void>;
+    /** One field of the hash under `key`, or null when either is missing. */
+    getField<T>(key: string, field: string): Promise<T | null>;
+    /**
+     * Writes one field of the hash under `key`, and gives the hash `ttl` seconds to live if it
+     * has no expiry yet - a hash written to every day still dies once a day. One round trip.
+     */
+    setField(key: string, field: string, value: unknown, ttl: number): Promise<void>;
+    /** Deletes one field of the hash under `key`; a missing field or hash is a no-op. One round trip. */
+    deleteField(key: string, field: string): Promise<void>;
 }
-export declare const createTaggedCache: (config: TaggedCacheConfig) => TaggedCache;
+export declare const createCache: (config: CacheConfig) => Cache;

package/dist/cache/index.js

@@ -1,17 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTaggedCache = exports.TaggedCache = void 0;
+exports.createCache = exports.Cache = exports.profileCacheKey = void 0;
 const redis_1 = require("@upstash/redis");
+const cache_1 = require("@managemint-solutions/entities/users/cache");
 /**
  * How long one Upstash call may take before it is abandoned. Every call here sits on the
- * request path - a portal boot on the read side, a profile write on the expiry side - so a
+ * request path - a portal boot on the read side, a profile write on the delete side - so a
  * stalled Redis must cost the caller a bounded wait and nothing more.
  */
 const REQUEST_TIMEOUT_MS = 3_000;
 /** One retry, briefly: the callers fail open, so patience only lengthens the miss. */
 const RETRY = { retries: 1, backoff: () => 200 };
-const tagSetKey = (tag) => `tag:${tag}`;
-class TaggedCache {
+/** The hash that holds an organization's cached member profiles. */
+const profileCacheKey = (organizationId) => `${cache_1.PROFILE_CACHE_KEY_PREFIX}${organizationId}`;
+exports.profileCacheKey = profileCacheKey;
+class Cache {
     redis;
     constructor(config) {
         this.redis = new redis_1.Redis({
@@ -24,36 +27,40 @@ class TaggedCache {
         });
     }
     /**
-     * The entry under `key`, or null when there is none. The value is JSON-parsed by the
+     * The string under `key`, or null when there is none. The value is JSON-parsed by the
      * client; `T` is the caller's promise about what was written, not a check.
      */
     get(key) {
         return this.redis.get(key);
     }
-    /** Writes `value` under `key` for `ttl` seconds, and files the key under each tag. One round trip. */
-    async set(key, value, { ttl, tags = [] }) {
-        const pipeline = this.redis.pipeline().set(key, value, { ex: ttl });
-        for (const tag of tags) {
-            // The set lives at least as long as its newest member, so a member can never outlive
-            // the set that would be used to find it.
-            pipeline.sadd(tagSetKey(tag), key).expire(tagSetKey(tag), ttl);
-        }
-        await pipeline.exec();
+    /** Writes `value` under `key` for `ttl` seconds. One round trip. */
+    async set(key, value, ttl) {
+        await this.redis.set(key, value, { ex: ttl });
     }
-    /** Deletes every entry filed under any of `tags`, and the tag sets themselves. Two round trips. */
-    async invalidateTag(tags) {
-        if (tags.length === 0) {
-            return;
-        }
-        const sets = tags.map(tagSetKey);
-        const read = this.redis.pipeline();
-        for (const set of sets) {
-            read.smembers(set);
-        }
-        const members = (await read.exec()).flat();
-        await this.redis.del(...new Set([...members, ...sets]));
+    /** Deletes `key` - a string or a whole hash. One round trip. */
+    async delete(key) {
+        await this.redis.del(key);
+    }
+    /** One field of the hash under `key`, or null when either is missing. */
+    getField(key, field) {
+        return this.redis.hget(key, field);
+    }
+    /**
+     * Writes one field of the hash under `key`, and gives the hash `ttl` seconds to live if it
+     * has no expiry yet - a hash written to every day still dies once a day. One round trip.
+     */
+    async setField(key, field, value, ttl) {
+        await this.redis
+            .pipeline()
+            .hset(key, { [field]: value })
+            .expire(key, ttl, 'NX')
+            .exec();
+    }
+    /** Deletes one field of the hash under `key`; a missing field or hash is a no-op. One round trip. */
+    async deleteField(key, field) {
+        await this.redis.hdel(key, field);
     }
 }
-exports.TaggedCache = TaggedCache;
-const createTaggedCache = (config) => new TaggedCache(config);
-exports.createTaggedCache = createTaggedCache;
+exports.Cache = Cache;
+const createCache = (config) => new Cache(config);
+exports.createCache = createCache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managemint-solutions/sdk",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Typed Supabase data-access SDK for ManageMint Solutions",
   "license": "UNLICENSED",
   "author": "Scott Bebington <scottbebington@gmail.com>",
@@ -51,7 +51,7 @@
     "testEnvironment": "node"
   },
   "dependencies": {
-    "@managemint-solutions/entities": "^1.17.0"
+    "@managemint-solutions/entities": "^1.20.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",