@desmat/redis-store 1.2.1 → 1.4.0

package/README.md

@@ -12,6 +12,8 @@ Leans into Redis’ strong suits to bring relational aspects to the simple but p
 
 Plays well with Upstash and Vercel but will work with any Redis instance via REST API.
 
+Also ships with `MemoryStore`, a pure in-memory implementation of `RedisStore` — a drop-in swap for local development and tests that don't need (or want) a live Redis instance. See [In-memory store](#in-memory-store) below.
+
 
 ## Installation
 
@@ -171,3 +173,50 @@ await Promise.all([
 // ZREM testthings:user:<USER_UUID> <UUID>
 // ...
 ```
+
+
+## In-memory store
+
+`MemoryStore<T>` implements the exact same `Store<T>` interface as `RedisStore<T>` but keeps everything in plain JS `Map`s — no Redis connection, no environment variables, no network calls. Application code written against `Store<T>` can swap between the two without any changes.
+
+```typescript
+import { MemoryStore } from '@desmat/redis-store';
+
+const store = {
+  users: new MemoryStore<User>({ key: "user" }),
+  things: new MemoryStore<Thing>({ key: "thing", options: ThingOptions }),
+};
+
+const user = await store.users.create({ name: "User One" });
+const things = await store.things.find({ user: user.id });
+```
+
+Useful for:
+- Local development without provisioning a real Redis instance
+- Test suites that need fast, isolated, disposable data (each `MemoryStore` instance is its own private state — nothing persists between processes, and nothing is shared unless you share the instance)
+
+Constructor accepts an optional `seed` array to pre-populate records (and their lookup indices) at construction time, so seeded data is immediately queryable via `find`/`ids` without needing to call `.create()` for each one:
+
+```typescript
+const things = new MemoryStore<Thing>({
+  key: "thing",
+  options: ThingOptions,
+  seed: [
+    { id: "thing-1", createdAt: Date.now(), createdBy: "user-1", label: "Seeded thing" },
+  ],
+});
+```
+
+Notes on parity with `RedisStore`:
+- `create`/`update`/`delete`/lookup/counter semantics are ported 1:1, including Redis's rank-based (not score-range) windowing for `count`/`offset` in `ids()`/`find()`, and `queryCounter`'s lexicographic range-bound behavior for `incCounters`/`queryCounter`.
+- `options.expire` is a no-op (data is ephemeral for the life of the process anyway).
+- There's no equivalent to `RedisStore`'s raw `.redis` client escape hatch — code that reaches through it directly for one-off scripts (rather than going through the `Store<T>` methods) isn't portable to `MemoryStore`.
+
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs the `MemoryStore` unit test suite (`test/*.test.ts`) via Node's built-in test runner (through `tsx`) — no live Redis needed. `RedisStore` itself has no automated tests; it's a thin wrapper around `@upstash/redis`.

package/dist/index copy.d.ts

@@ -0,0 +1,60 @@
+import { Redis } from "@upstash/redis";
+export type RedisStoreRecord = {
+    id: string;
+    createdAt: number;
+    updatedAt?: number;
+    deletedAt?: number;
+};
+export default class RedisStore<T extends RedisStoreRecord> {
+    redis: Redis;
+    key: string;
+    setKey: string;
+    valueKey: (id: string) => string;
+    options: any;
+    debug: boolean;
+    constructor({ url, token, key, setKey, options, debug, }: {
+        key: string;
+        setKey?: string;
+        options?: any;
+        url?: string;
+        token?: string;
+        debug?: boolean;
+    });
+    lookupKeys(value: any, options?: {
+        noLookup?: boolean;
+        lookups?: any;
+    }): any[][];
+    exists(id: string): Promise<boolean>;
+    get(id: string, options?: any): Promise<T | undefined>;
+    scan(query?: any): Promise<Set<string>>;
+    ids(query?: any, options?: {
+        withScores?: boolean;
+        aggregate?: string;
+    }): Promise<Set<string>>;
+    find(query?: any): Promise<T[]>;
+    create(value: any, options?: {
+        expire?: number;
+        noIndex?: boolean;
+        score?: number;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T>;
+    update(value: any, options?: any): Promise<T>;
+    incrementCounters(values: Record<string, string | number>, delta: {
+        total: number;
+        count: number;
+    }): Promise<any>;
+    queryCounter(kind: "count" | "counts" | "totals", dims: string[], exact: Record<string, string | number>, range?: {
+        field: string;
+        min?: string;
+        max?: string;
+    }): Promise<number | Array<{
+        member: string;
+        score: number;
+    }>>;
+    delete(id: string, options?: {
+        hardDelete?: boolean;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T | undefined>;
+}

package/dist/index copy.js

@@ -0,0 +1,356 @@
+"use strict";
+/*
+    Some useful commands
+
+    keys *
+    scan 0 match thing:*
+    del thing1 thing2 etc
+    json.get things $
+    json.get things '$[?((@.deletedAt > 0) == false)]'
+    json.get things '$[?((@.deletedAt > 0) == true)]'
+    json.get things '$[?(@.createdBy == "UID")]'
+    json.get things '$[?(@.content ~= "(?i)lorem")]'
+    json.get things '$[?(@.id ~= "(ID1)|(ID2)")]
+    json.set thing:UUID '$.foos[5].bar' '{"car": 42}'
+    json.set thing:UUID '$.foos[1].bar.car' '42'
+    json.get userhaikus '$[?(@.haikuId == "ID" && (@.likedAt > 0) == true)]'
+*/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const moment_1 = __importDefault(require("moment"));
+const utils_1 = require("@desmat/utils");
+const redis_1 = require("@upstash/redis");
+// polyfill Set.intersection
+;
+(function () {
+    // @ts-ignore
+    if (!Set.prototype.intersection) {
+        // @ts-ignore    
+        Set.prototype.intersection = function (other) {
+            return new Set(Array.from(this).filter((value) => other.has(value)));
+        };
+    }
+})();
+class RedisStore {
+    constructor({ url, token, key, setKey, options, debug, }) {
+        const _url = url || process.env.KV_REST_API_URL; //|| "https://crisp-skylark-47483.upstash.io";
+        const _token = token || process.env.KV_REST_API_TOKEN; //|| "Abl7AAIncDFiZDM3ZjVjOTEyMmI0MWYxOWRkYTlhMWVkYWQ3ZGRjN3AxNDc0ODM";
+        if (!_url)
+            throw 'Error creating RedisStore: `url` is required: either provide in constructor or via environment variable `KV_REST_API_URL`';
+        if (!_token)
+            throw 'Error creating RedisStore: `token` is required: either provide in constructor or via environment variable `KV_REST_API_TOKEN`';
+        this.redis = new redis_1.Redis({
+            url: _url,
+            token: _token
+        });
+        this.key = key;
+        this.setKey = setKey || key + "s";
+        this.valueKey = (id) => `${key}:${id}`;
+        this.options = options;
+        this.debug = !!debug;
+    }
+    lookupKeys(value, options) {
+        options = { ...this.options, ...options };
+        this.debug && console.log(`RedisStore.lookupKeys<${this.key}>.lookupKeys`, { value, options });
+        /*
+          create index and lookup sets based on options.lookups
+    
+          given a likedhaiku record:
+          {
+            id: 123:456,
+            userId: 123,
+            haikuId 456,
+          }
+    
+          and lookups:
+          {
+            user: { userId: "haikuId"},
+            haiku: { haikuId: "userId" }
+          }
+      
+          we want indexes:
+    
+          likedhaiku:123:456 -> value (JSON, the rest are sorted sets, not handled here)
+          likedhaikus -> all likedhaiku id's (ie 123:456, etc, not handled here)
+          // NOT SUPPORTED FOR NOW // likedhaikus:users -> all user ids (ie 123, etc) NOTE: this should be a sorted set of user ids with its score as number of haikus liked
+          likedhaikus:user:123 -> all likedhaiku id's for the given user (ie 123:456, etc)
+          // NOT SUPPORTED FOR NOW // likedhaikus:haikus ->  NOTE: this should be a sorted set of haiku ids with its score as number of users who liked it
+          likedhaikus:haiku:456 -> all likedhaiku id's for the given haiku (ie 123:456, etc)
+    
+        */
+        const lookupKeys = !(options === null || options === void 0 ? void 0 : options.noLookup) && Object
+            .entries((options === null || options === void 0 ? void 0 : options.lookups) || {})
+            .map((entry) => {
+            const id = value.id;
+            const lookupName = entry[0];
+            const lookupKey = entry[1];
+            // TODO validate and log errors
+            // @ts-ignore
+            const lookupId = value[lookupKey];
+            // foos:bar:123 -> 123:456
+            return [`${this.setKey}:${lookupName}:${lookupId}`, id];
+        }) || [];
+        this.debug && console.log(`RedisStore<${this.key}>.lookupKeys`, { options, lookupKeys });
+        return lookupKeys;
+    }
+    async exists(id) {
+        this.debug && console.log(`RedisStore<${this.key}>.exists`, { id });
+        const response = await this.redis.exists(this.valueKey(id));
+        this.debug && console.log(`RedisStore<${this.key}>.exists`, { response });
+        return response > 0;
+    }
+    async get(id, options) {
+        this.debug && console.log(`RedisStore<${this.key}>.get`, { id });
+        const response = await this.redis.json.get(this.valueKey(id), "$");
+        this.debug && console.log(`RedisStore<${this.key}>.get`, { response });
+        let value;
+        if (response && response[0] && !(response[0].deletedAt && !(options === null || options === void 0 ? void 0 : options.deleted))) {
+            value = response[0];
+        }
+        return value;
+    }
+    async scan(query = {}) {
+        this.debug && console.log(`RedisStore<${this.key}>.scan`, { query });
+        !query.count && console.warn(`RedisStore.RedisStore<${this.key}>.find WARNING: scan command with no count provided: setting count at 999`);
+        const count = query.count || 999;
+        const match = this.valueKey(query.scan);
+        let keys = new Set();
+        let nextCursor = "0";
+        do {
+            const ret = await this.redis.scan(nextCursor, { match, type: "json", count: count - keys.size });
+            this.debug && console.log(`RedisStore<${this.key}>.scan`, { ret });
+            nextCursor = ret[0];
+            ret[1].forEach((key) => keys.size < count && keys.add(key.substring(key.indexOf(':') + 1)));
+        } while (keys.size < count && nextCursor && nextCursor != "0");
+        this.debug && console.log(`RedisStore<${this.key}>.scan`, { keys });
+        return keys;
+    }
+    async ids(query = {}, options) {
+        this.debug && console.log(`RedisStore<${this.key}>.ids`, { query });
+        if (query.scan) {
+            return this.scan(query);
+        }
+        let count = query.count;
+        delete query.count;
+        if (typeof (count) != "undefined" && typeof (count) != "number") {
+            console.warn(`RedisStore.RedisStore<${this.key}>.id WARNING: query.count is not a number`);
+            count = undefined;
+        }
+        let offset = query.offset;
+        delete query.offset;
+        if (typeof (offset) != "undefined" && typeof (offset) != "number") {
+            console.warn(`RedisStore.RedisStore<${this.key}>.id WARNING: query.offset must be a number`);
+            offset = undefined;
+        }
+        const min = offset || 0;
+        const max = min + (count || 0) - 1;
+        const queryEntries = query && Object.entries(query);
+        if (options === null || options === void 0 ? void 0 : options.withScores) {
+            // const setOfIds = await Promise.all(
+            //   queryEntries.map(([queryKey, queryVal]: [string, string]) => {
+            //     if (queryVal) {
+            //       // lookup keys via the foos:bar:123 lookup set
+            //       return this.redis.zrange(`${this.setKey}:${queryKey}:${queryVal}`, min, max, { rev: true, withScores: !!options?.withScores });
+            //     } else {
+            //       throw `redis.find(query) query must have key and value`;
+            //     }
+            //   })
+            // );
+            const keys = queryEntries.map(([queryKey, queryVal]) => `${queryKey}:${queryVal}`);
+            const overallKey = `${this.setKey}:${keys.join(":")}`;
+            const zinterstoreRet = await this.redis.zinterstore(overallKey, keys.length, keys.map((k) => `${this.setKey}:${k}`), { aggregate: "min" });
+            const zrangeRet = await this.redis.zrange(overallKey, min, max, { rev: true, withScores: !!(options === null || options === void 0 ? void 0 : options.withScores) });
+            console.warn(`RedisStore.RedisStore<${this.key}>.ids`, { overallKey, keys, zinterstoreRet, zrangeRet });
+            // const ids = setOfIds.reduce((prev: Set<any> | undefined, curr: any[]) => {
+            //   new Set(curr).intersection(prev || new Set(curr)), undefined)
+            // throw 'NOT IMPLEMENTED';
+        }
+        // .ids() or .ids({})
+        if (!(queryEntries === null || queryEntries === void 0 ? void 0 : queryEntries.length)) {
+            // get all keys via the index set
+            return new Set(await this.redis.zrange(`${this.setKey}`, min, max, { rev: true /* , withScores: !!options?.withScores */ }));
+        }
+        // .ids({ foo: "FOO", bar: "BAR", ... })
+        const setOfIds = await Promise.all(queryEntries.map(([queryKey, queryVal]) => {
+            if (queryVal) {
+                // lookup keys via the foos:bar:123 lookup set
+                return this.redis.zrange(`${this.setKey}:${queryKey}:${queryVal}`, min, max, { rev: true /* , withScores: !!options?.withScores */ });
+            }
+            else {
+                throw `redis.find(query) query must have key and value`;
+            }
+        }));
+        // @ts-ignore
+        const ids = setOfIds.reduce((prev, curr) => new Set(curr).intersection(prev || new Set(curr)), undefined);
+        this.debug && console.log(`RedisStore<${this.key}>.ids queried lookup key`, { query, setOfIds, ids });
+        return ids;
+    }
+    async find(query = {}) {
+        this.debug && console.log(`RedisStore<${this.key}>.find`, { query });
+        const keys = Array.isArray(query.id)
+            ? query.id
+                .map((id) => id && this.valueKey(id))
+                .filter(Boolean)
+            : Array.from(await this.ids(query))
+                // @ts-ignore
+                .map((key) => `${this.key}:${key}`);
+        if (keys.length > 100) {
+            console.warn(`RedisStore.RedisStore<${this.key}>.find WARNING: json.mget more than 100 values`, { keys });
+        }
+        else {
+            this.debug && console.log(`RedisStore<${this.key}>.find`, { keys });
+        }
+        // don't mget too many at once otherwise 💥
+        const blockSize = 256;
+        const blocks = keys && keys.length && Array
+            .apply(null, Array(Math.ceil(keys.length / blockSize)))
+            .map((v, block) => (keys || [])
+            .slice(blockSize * block, blockSize * (block + 1)));
+        this.debug && console.log(`RedisStore<${this.key}>.find`, { blocks });
+        const values = blocks && blocks.length > 0
+            ? (await Promise.all(blocks
+                .map(async (keys) => (await this.redis.json.mget(keys, "$"))
+                .flat())))
+                .flat()
+                .filter((value) => value && !value.deletedAt)
+            : [];
+        this.debug && console.log(`RedisStore<${this.key}>.find`, { values });
+        return values;
+    }
+    async create(value, options) {
+        this.debug && console.log(`RedisStore<${this.key}>.create`, { value, options, this_options: this.options });
+        const now = (0, moment_1.default)().valueOf();
+        options = { ...this.options, ...options };
+        const createdValue = {
+            id: value.id || (0, utils_1.uuid)(),
+            createdAt: value.createdAt || now,
+            ...value,
+        };
+        this.debug && console.log(`RedisStore<${this.key}>.create`, { createdValue });
+        const lookupKeys = this.lookupKeys(createdValue, options);
+        this.debug && console.log(`RedisStore<${this.key}>.create`, { lookupKeys });
+        const responses = await Promise.all([
+            this.redis.json.set(this.valueKey(createdValue.id), "$", createdValue),
+            (options === null || options === void 0 ? void 0 : options.expire) && this.redis.expire(this.valueKey(createdValue.id), options === null || options === void 0 ? void 0 : options.expire),
+            // !options?.noIndex && this.redis.zadd(this.setKey, { score: options?.score || createdValue.createdAt, member: createdValue.id }),
+            // ...(lookupKeys ? lookupKeys.map((lookupKey: any) => this.redis.zadd(lookupKey[0], { score: options?.score || createdValue.createdAt, member: lookupKey[1] })) : []),
+            ...(lookupKeys ? lookupKeys.map((lookupKey) => this.redis.zincrby(lookupKey[0], (options === null || options === void 0 ? void 0 : options.score) || createdValue.createdAt, lookupKey[1])) : []),
+        ]);
+        this.debug && console.log(`RedisStore<${this.key}>.create`, { responses });
+        return createdValue;
+    }
+    async update(value, options) {
+        this.debug && console.log(`RedisStore<${this.key}>.update`, { value, options });
+        if (!value.id) {
+            throw `Cannot update ${this.key}: null id`;
+        }
+        const prevValue = await this.get(value.id);
+        if (!prevValue) {
+            throw `Cannot update ${this.key}: does not exist: ${value.id}`;
+        }
+        const now = (0, moment_1.default)().valueOf();
+        options = { ...this.options, ...options };
+        const updatedValue = {
+            ...value,
+            updatedAt: now,
+        };
+        // optionally update lookups 
+        // @ts-ignore
+        const prevLookupKeys = new Map(this.lookupKeys(prevValue, options));
+        // @ts-ignore
+        const lookupKeys = new Map(this.lookupKeys(updatedValue, options));
+        const lookupsToRemove = prevLookupKeys && Array.from(prevLookupKeys)
+            .filter(([k, v]) => !lookupKeys || lookupKeys.get(k) != v);
+        const lookupsToAdd = lookupKeys && Array.from(lookupKeys)
+            .filter(([k, v]) => !prevLookupKeys || prevLookupKeys.get(k) != v);
+        this.debug && console.log(`RedisStore<${this.key}>.update`, { prevLookupKeys, lookupKeys, prevLookupKeyMap: prevLookupKeys, keysToRemove: lookupsToRemove, keysToAdd: lookupsToAdd });
+        if (lookupsToRemove && lookupsToRemove.length) {
+            this.debug && console.log(`RedisStore<${this.key}>.update deleting previous lookup keys`, { prevLookupKeys });
+            const response = await Promise.all([
+                ...lookupsToRemove.map((lookupKey) => this.redis.zrem(lookupKey[0], lookupKey[1]))
+            ]);
+            this.debug && console.log(`RedisStore<${this.key}>.update deleted previous lookup keys`, { response });
+        }
+        const response = await Promise.all([
+            this.redis.json.set(this.valueKey(value.id), "$", updatedValue),
+            options.expire && this.redis.expire(this.valueKey(value.id), options.expire),
+            ...(lookupsToAdd ? lookupsToAdd.map((lookupKey) => this.redis.zadd(lookupKey[0], { score: updatedValue.createdAt || updatedValue.updatedAt, member: lookupKey[1] })) : []),
+        ]);
+        this.debug && console.log(`RedisStore<${this.key}>.update`, { response });
+        return updatedValue;
+    }
+    async incrementCounters(values, delta) {
+        var _a;
+        this.debug && console.log(`RedisStore<${this.key}>.incrementCounters`, { values, delta });
+        const counters = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.counters) || [];
+        const responses = await Promise.all(counters
+            .filter((dims) => dims.every((d) => typeof values[d] != "undefined"))
+            .flatMap((dims) => {
+            const member = dims.map((d) => `${d}=${values[d]}`).join(":");
+            return [
+                this.redis.zincrby(`${this.key}Totals:${dims.join(":")}`, delta.total, member),
+                this.redis.zincrby(`${this.key}Counts:${dims.join(":")}`, delta.count, member),
+            ];
+        }));
+        this.debug && console.log(`RedisStore<${this.key}>.incrementCounters`, { responses });
+        return responses;
+    }
+    async queryCounter(kind, dims, exact, range) {
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { kind, dims, exact, range });
+        const setKey = `${this.key}${kind == "totals" ? "Totals" : "Counts"}:${dims.join(":")}`;
+        const prefix = dims
+            .filter((d) => typeof exact[d] != "undefined")
+            .map((d) => `${d}=${exact[d]}`)
+            .join(":");
+        // the trailing sentinel scopes the range to the "prefix:" family regardless of whether
+        // the range field itself is the last dim, matching how the original hand-rolled queries worked
+        const hasMore = dims.length > Object.keys(exact).length;
+        const minPrefix = (range === null || range === void 0 ? void 0 : range.min) != null ? `${prefix}${prefix ? ":" : ""}${range.field}=${range.min}` : prefix;
+        const maxPrefix = (range === null || range === void 0 ? void 0 : range.max) != null ? `${prefix}${prefix ? ":" : ""}${range.field}=${range.max}` : prefix;
+        const min = `[${minPrefix}${hasMore ? ":\x00" : ""}`;
+        const max = `[${maxPrefix}${hasMore ? ":\x7f" : ""}`;
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { setKey, min, max });
+        if (kind == "count") {
+            const count = await this.redis.zlexcount(setKey, min, max);
+            this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { count });
+            return count;
+        }
+        const raw = await this.redis.zrange(setKey, min, max, { byLex: true, withScores: true });
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { raw });
+        // members are returned as-is ("field=value:field=value...") rather than parsed into an
+        // object: some field values (eg namespaced ids) may themselves contain the ":" delimiter,
+        // which only the caller can safely account for when splitting a member back into fields
+        const results = [];
+        for (let i = 0; i < raw.length / 2; i++) {
+            results.push({ member: `${raw[2 * i]}`, score: raw[2 * i + 1] });
+        }
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { results });
+        return results;
+    }
+    async delete(id, options) {
+        this.debug && console.log(`RedisStore<${this.key}>.delete`, { id, options });
+        if (!id) {
+            throw `Cannot delete ${this.key}: null id`;
+        }
+        options = { ...this.options, ...options };
+        const value = await this.get(id, { deleted: true });
+        if (!value) {
+            console.warn(`RedisStore<${this.key}>.delete WARNING: does not exist: ${id}`);
+        }
+        const lookupKeys = value && this.lookupKeys(value, options);
+        this.debug && console.log(`RedisStore<${this.key}>.delete`, { lookupKeys });
+        const deletedAt = (0, moment_1.default)().valueOf();
+        const response = await Promise.all([
+            (options === null || options === void 0 ? void 0 : options.hardDelete)
+                ? this.redis.json.del(this.valueKey(id), "$")
+                : this.redis.json.set(this.valueKey(id), "$.deletedAt", deletedAt),
+            this.redis.zrem(this.setKey, id),
+            ...(lookupKeys ? lookupKeys.map((lookupKey) => this.redis.zrem(lookupKey[0], lookupKey[1])) : []),
+        ]);
+        this.debug && console.log(`RedisStore<${this.key}>.delete`, { response });
+        return value ? { ...value, deletedAt } : undefined;
+    }
+}
+exports.default = RedisStore;

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 import { Redis } from "@upstash/redis";
+import type { Store } from "./store";
 export type RedisStoreRecord = {
     id: string;
     createdAt: number;
     updatedAt?: number;
     deletedAt?: number;
 };
-export default class RedisStore<T extends RedisStoreRecord> {
+export { Store } from "./store";
+export { default as MemoryStore } from "./memory-store";
+export default class RedisStore<T extends RedisStoreRecord> implements Store<T> {
     redis: Redis;
     key: string;
     setKey: string;
@@ -20,13 +23,38 @@ export default class RedisStore<T extends RedisStoreRecord> {
         token?: string;
         debug?: boolean;
     });
-    lookupKeys(value: any, options?: any): any[][];
+    lookupKeys(value: any, options?: {
+        noLookup?: boolean;
+        lookups?: any;
+    }): any[][];
     exists(id: string): Promise<boolean>;
     get(id: string, options?: any): Promise<T | undefined>;
     scan(query?: any): Promise<Set<string>>;
     ids(query?: any): Promise<Set<string>>;
     find(query?: any): Promise<T[]>;
-    create(value: any, options?: any): Promise<T>;
+    create(value: any, options?: {
+        expire?: number;
+        noIndex?: boolean;
+        score?: number;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T>;
     update(value: any, options?: any): Promise<T>;
-    delete(id: string, options?: any): Promise<T | undefined>;
+    incCounters(values: Record<string, string | number>, delta: {
+        total: number;
+        count: number;
+    }): Promise<any>;
+    queryCounter(kind: "count" | "counts" | "totals", counter: string, exact: Record<string, string | number>, range?: {
+        field: string;
+        min?: string;
+        max?: string;
+    }): Promise<number | Array<{
+        member: string;
+        score: number;
+    }>>;
+    delete(id: string, options?: {
+        hardDelete?: boolean;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T | undefined>;
 }

package/dist/index.js

@@ -19,9 +19,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = void 0;
 const moment_1 = __importDefault(require("moment"));
 const utils_1 = require("@desmat/utils");
 const redis_1 = require("@upstash/redis");
+var memory_store_1 = require("./memory-store");
+Object.defineProperty(exports, "MemoryStore", { enumerable: true, get: function () { return __importDefault(memory_store_1).default; } });
 // polyfill Set.intersection
 ;
 (function () {
@@ -213,8 +216,8 @@ class RedisStore {
         this.debug && console.log(`RedisStore<${this.key}>.create`, { lookupKeys });
         const responses = await Promise.all([
             this.redis.json.set(this.valueKey(createdValue.id), "$", createdValue),
-            options.expire && this.redis.expire(this.valueKey(createdValue.id), options.expire),
-            !options.noIndex && this.redis.zadd(this.setKey, { score: createdValue.createdAt, member: createdValue.id }),
+            (options === null || options === void 0 ? void 0 : options.expire) && this.redis.expire(this.valueKey(createdValue.id), options === null || options === void 0 ? void 0 : options.expire),
+            !(options === null || options === void 0 ? void 0 : options.noIndex) && this.redis.zadd(this.setKey, { score: createdValue.createdAt, member: createdValue.id }),
             ...(lookupKeys ? lookupKeys.map((lookupKey) => this.redis.zadd(lookupKey[0], { score: createdValue.createdAt, member: lookupKey[1] })) : []),
         ]);
         this.debug && console.log(`RedisStore<${this.key}>.create`, { responses });
@@ -260,7 +263,62 @@ class RedisStore {
         this.debug && console.log(`RedisStore<${this.key}>.update`, { response });
         return updatedValue;
     }
-    async delete(id, options = {}) {
+    async incCounters(values, delta) {
+        var _a;
+        this.debug && console.log(`RedisStore<${this.key}>.incCounters`, { values, delta });
+        const counters = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.counters) || [];
+        counters
+            .filter((counter) => !counter.split(":").every((d) => typeof values[d] != "undefined"))
+            .forEach((counter) => {
+            const missing = counter.split(":").filter((d) => typeof values[d] == "undefined");
+            console.warn(`RedisStore<${this.key}>.incCounters WARNING: skipping counter "${counter}": missing dimension(s) ${missing.join(", ")} in values`, { values });
+        });
+        const responses = await Promise.all(counters
+            .filter((counter) => counter.split(":").every((d) => typeof values[d] != "undefined"))
+            .flatMap((counter) => {
+            const member = counter.split(":").map((d) => `${d}=${values[d]}`).join(":");
+            return [
+                this.redis.zincrby(`${this.key}Totals:${counter}`, delta.total, member),
+                this.redis.zincrby(`${this.key}Counts:${counter}`, delta.count, member),
+            ];
+        }));
+        this.debug && console.log(`RedisStore<${this.key}>.incCounters`, { responses });
+        return responses;
+    }
+    async queryCounter(kind, counter, exact, range) {
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { kind, counter, exact, range });
+        const dims = counter.split(":");
+        const setKey = `${this.key}${kind == "totals" ? "Totals" : "Counts"}:${counter}`;
+        const prefix = dims
+            .filter((d) => typeof exact[d] != "undefined")
+            .map((d) => `${d}=${exact[d]}`)
+            .join(":");
+        // the trailing sentinel scopes the range to the "prefix:" family regardless of whether
+        // the range field itself is the last dim, matching how the original hand-rolled queries worked
+        const hasMore = dims.length > Object.keys(exact).length;
+        const minPrefix = (range === null || range === void 0 ? void 0 : range.min) != null ? `${prefix}${prefix ? ":" : ""}${range.field}=${range.min}` : prefix;
+        const maxPrefix = (range === null || range === void 0 ? void 0 : range.max) != null ? `${prefix}${prefix ? ":" : ""}${range.field}=${range.max}` : prefix;
+        const min = `[${minPrefix}${hasMore ? ":\x00" : ""}`;
+        const max = `[${maxPrefix}${hasMore ? ":\x7f" : ""}`;
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { setKey, min, max });
+        if (kind == "count") {
+            const count = await this.redis.zlexcount(setKey, min, max);
+            this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { count });
+            return count;
+        }
+        const raw = await this.redis.zrange(setKey, min, max, { byLex: true, withScores: true });
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { raw });
+        // members are returned as-is ("field=value:field=value...") rather than parsed into an
+        // object: some field values (eg namespaced ids) may themselves contain the ":" delimiter,
+        // which only the caller can safely account for when splitting a member back into fields
+        const results = [];
+        for (let i = 0; i < raw.length / 2; i++) {
+            results.push({ member: `${raw[2 * i]}`, score: raw[2 * i + 1] });
+        }
+        this.debug && console.log(`RedisStore<${this.key}>.queryCounter`, { results });
+        return results;
+    }
+    async delete(id, options) {
         this.debug && console.log(`RedisStore<${this.key}>.delete`, { id, options });
         if (!id) {
             throw `Cannot delete ${this.key}: null id`;
@@ -274,7 +332,7 @@ class RedisStore {
         this.debug && console.log(`RedisStore<${this.key}>.delete`, { lookupKeys });
         const deletedAt = (0, moment_1.default)().valueOf();
         const response = await Promise.all([
-            options.hardDelete
+            (options === null || options === void 0 ? void 0 : options.hardDelete)
                 ? this.redis.json.del(this.valueKey(id), "$")
                 : this.redis.json.set(this.valueKey(id), "$.deletedAt", deletedAt),
             this.redis.zrem(this.setKey, id),

package/dist/memory-store.d.ts

@@ -0,0 +1,54 @@
+import type { RedisStoreRecord } from "./index";
+import type { Store } from "./store";
+export default class MemoryStore<T extends RedisStoreRecord> implements Store<T> {
+    key: string;
+    setKey: string;
+    options: any;
+    debug: boolean;
+    private records;
+    private index;
+    private lookups;
+    private counters;
+    constructor({ key, setKey, options, debug, seed, }: {
+        key: string;
+        setKey?: string;
+        options?: any;
+        debug?: boolean;
+        seed?: T[];
+    });
+    lookupKeys(value: any, options?: {
+        noLookup?: boolean;
+        lookups?: any;
+    }): any[][];
+    private _index;
+    exists(id: string): Promise<boolean>;
+    get(id: string, options?: any): Promise<T | undefined>;
+    scan(query?: any): Promise<Set<string>>;
+    ids(query?: any): Promise<Set<string>>;
+    find(query?: any): Promise<T[]>;
+    create(value: any, options?: {
+        expire?: number;
+        noIndex?: boolean;
+        score?: number;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T>;
+    update(value: any, options?: any): Promise<T>;
+    incCounters(values: Record<string, string | number>, delta: {
+        total: number;
+        count: number;
+    }): Promise<any>;
+    queryCounter(kind: "count" | "counts" | "totals", counter: string, exact: Record<string, string | number>, range?: {
+        field: string;
+        min?: string;
+        max?: string;
+    }): Promise<number | Array<{
+        member: string;
+        score: number;
+    }>>;
+    delete(id: string, options?: {
+        hardDelete?: boolean;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T | undefined>;
+}

package/dist/memory-store.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@desmat/utils");
+// mimics a Redis sorted set: members ordered by score, ties broken by member
+// string ascending (Redis zset default ordering), with ZRANGE's index semantics
+// (negative indices count from the end, e.g. -1 is the last element).
+class SortedIdList {
+    constructor() {
+        this.entries = [];
+    }
+    add(id, score) {
+        this.remove(id);
+        this.entries.push({ id, score });
+    }
+    remove(id) {
+        this.entries = this.entries.filter((e) => e.id !== id);
+    }
+    sorted() {
+        return [...this.entries].sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    range(min, max, rev) {
+        const ordered = rev ? this.sorted().reverse() : this.sorted();
+        const len = ordered.length;
+        const resolve = (i) => (i < 0 ? len + i : i);
+        const start = Math.max(resolve(min), 0);
+        const stop = Math.min(resolve(max), len - 1);
+        if (len === 0 || start > stop)
+            return [];
+        return ordered.slice(start, stop + 1).map((e) => e.id);
+    }
+}
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+}
+// intersect() polyfills Set.prototype.intersection so this module has no load-order
+// dependency on index.ts's IIFE that installs it globally.
+function intersect(a, b) {
+    return new Set(Array.from(a).filter((value) => b.has(value)));
+}
+class MemoryStore {
+    constructor({ key, setKey, options, debug, seed, }) {
+        this.records = new Map();
+        this.index = new SortedIdList();
+        this.lookups = new Map();
+        this.counters = new Map();
+        this.key = key;
+        this.setKey = setKey || key + "s";
+        this.options = options;
+        this.debug = !!debug;
+        (seed || []).forEach((value) => this._index(value));
+    }
+    lookupKeys(value, options) {
+        options = { ...this.options, ...options };
+        this.debug && console.log(`MemoryStore<${this.key}>.lookupKeys`, { value, options });
+        const lookupKeys = !(options === null || options === void 0 ? void 0 : options.noLookup) && Object
+            .entries((options === null || options === void 0 ? void 0 : options.lookups) || {})
+            .map((entry) => {
+            const id = value.id;
+            const lookupName = entry[0];
+            const lookupKey = entry[1];
+            // @ts-ignore
+            const lookupId = value[lookupKey];
+            return [`${this.setKey}:${lookupName}:${lookupId}`, id];
+        }) || [];
+        this.debug && console.log(`MemoryStore<${this.key}>.lookupKeys`, { options, lookupKeys });
+        return lookupKeys;
+    }
+    // shared by the constructor's `seed` and create(): adds a record to the main
+    // index and lookup indices without re-deriving id/createdAt defaults.
+    _index(value, options) {
+        this.records.set(value.id, value);
+        !(options === null || options === void 0 ? void 0 : options.noIndex) && this.index.add(value.id, value.createdAt);
+        const lookupKeys = this.lookupKeys(value, options);
+        (lookupKeys || []).forEach(([lookupKey, id]) => {
+            if (!this.lookups.has(lookupKey))
+                this.lookups.set(lookupKey, new SortedIdList());
+            this.lookups.get(lookupKey).add(id, value.createdAt);
+        });
+    }
+    async exists(id) {
+        this.debug && console.log(`MemoryStore<${this.key}>.exists`, { id });
+        return this.records.has(id);
+    }
+    async get(id, options) {
+        this.debug && console.log(`MemoryStore<${this.key}>.get`, { id });
+        const value = this.records.get(id);
+        return value && !(value.deletedAt && !(options === null || options === void 0 ? void 0 : options.deleted)) ? value : undefined;
+    }
+    async scan(query = {}) {
+        var _a;
+        this.debug && console.log(`MemoryStore<${this.key}>.scan`, { query });
+        const count = query.count || 999;
+        const pattern = globToRegExp((_a = query.scan) !== null && _a !== void 0 ? _a : "*");
+        const keys = new Set();
+        for (const id of this.records.keys()) {
+            if (keys.size >= count)
+                break;
+            if (pattern.test(id))
+                keys.add(id);
+        }
+        this.debug && console.log(`MemoryStore<${this.key}>.scan`, { keys });
+        return keys;
+    }
+    async ids(query = {}) {
+        this.debug && console.log(`MemoryStore<${this.key}>.ids`, { query });
+        if (query.scan) {
+            return this.scan(query);
+        }
+        let count = query.count;
+        delete query.count;
+        if (typeof (count) != "undefined" && typeof (count) != "number") {
+            console.warn(`MemoryStore<${this.key}>.ids WARNING: query.count is not a number`);
+            count = undefined;
+        }
+        let offset = query.offset;
+        delete query.offset;
+        if (typeof (offset) != "undefined" && typeof (offset) != "number") {
+            console.warn(`MemoryStore<${this.key}>.ids WARNING: query.offset must be a number`);
+            offset = undefined;
+        }
+        const min = offset || 0;
+        const max = min + (count || 0) - 1;
+        const queryEntries = query && Object.entries(query);
+        if (!(queryEntries === null || queryEntries === void 0 ? void 0 : queryEntries.length)) {
+            return new Set(this.index.range(min, max, true));
+        }
+        const setOfIds = queryEntries.map(([queryKey, queryVal]) => {
+            var _a;
+            if (queryVal) {
+                const lookupKey = `${this.setKey}:${queryKey}:${queryVal}`;
+                return new Set(((_a = this.lookups.get(lookupKey)) === null || _a === void 0 ? void 0 : _a.range(min, max, true)) || []);
+            }
+            else {
+                throw `MemoryStore.ids(query) query must have key and value`;
+            }
+        });
+        const ids = setOfIds.reduce((prev, curr) => intersect(curr, prev || curr), undefined) || new Set();
+        this.debug && console.log(`MemoryStore<${this.key}>.ids queried lookup key`, { query, setOfIds, ids });
+        return ids;
+    }
+    async find(query = {}) {
+        this.debug && console.log(`MemoryStore<${this.key}>.find`, { query });
+        const ids = Array.isArray(query.id)
+            ? query.id.filter(Boolean)
+            : Array.from(await this.ids(query));
+        const values = ids
+            .map((id) => this.records.get(id))
+            .filter((value) => !!value && !value.deletedAt);
+        this.debug && console.log(`MemoryStore<${this.key}>.find`, { values });
+        return values;
+    }
+    async create(value, options) {
+        this.debug && console.log(`MemoryStore<${this.key}>.create`, { value, options, this_options: this.options });
+        const now = Date.now();
+        options = { ...this.options, ...options };
+        const createdValue = {
+            id: value.id || (0, utils_1.uuid)(),
+            createdAt: value.createdAt || now,
+            ...value,
+        };
+        this.debug && console.log(`MemoryStore<${this.key}>.create`, { createdValue });
+        this._index(createdValue, options);
+        (options === null || options === void 0 ? void 0 : options.expire) && this.debug && console.log(`MemoryStore<${this.key}>.create ignoring options.expire (memory store is ephemeral)`);
+        return createdValue;
+    }
+    async update(value, options) {
+        this.debug && console.log(`MemoryStore<${this.key}>.update`, { value, options });
+        if (!value.id) {
+            throw `Cannot update ${this.key}: null id`;
+        }
+        const prevValue = await this.get(value.id);
+        if (!prevValue) {
+            throw `Cannot update ${this.key}: does not exist: ${value.id}`;
+        }
+        const now = Date.now();
+        options = { ...this.options, ...options };
+        const updatedValue = {
+            ...value,
+            updatedAt: now,
+        };
+        // @ts-ignore
+        const prevLookupKeys = new Map(this.lookupKeys(prevValue, options));
+        // @ts-ignore
+        const lookupKeys = new Map(this.lookupKeys(updatedValue, options));
+        const lookupsToRemove = prevLookupKeys && Array.from(prevLookupKeys)
+            .filter(([k, v]) => !lookupKeys || lookupKeys.get(k) != v);
+        const lookupsToAdd = lookupKeys && Array.from(lookupKeys)
+            .filter(([k, v]) => !prevLookupKeys || prevLookupKeys.get(k) != v);
+        this.debug && console.log(`MemoryStore<${this.key}>.update`, { prevLookupKeys, lookupKeys, keysToRemove: lookupsToRemove, keysToAdd: lookupsToAdd });
+        lookupsToRemove.forEach(([lookupKey, id]) => { var _a; return (_a = this.lookups.get(lookupKey)) === null || _a === void 0 ? void 0 : _a.remove(id); });
+        this.records.set(value.id, updatedValue);
+        lookupsToAdd.forEach(([lookupKey, id]) => {
+            if (!this.lookups.has(lookupKey))
+                this.lookups.set(lookupKey, new SortedIdList());
+            this.lookups.get(lookupKey).add(id, updatedValue.createdAt || updatedValue.updatedAt);
+        });
+        return updatedValue;
+    }
+    async incCounters(values, delta) {
+        var _a;
+        this.debug && console.log(`MemoryStore<${this.key}>.incCounters`, { values, delta });
+        const counters = ((_a = this.options) === null || _a === void 0 ? void 0 : _a.counters) || [];
+        counters
+            .filter((counter) => !counter.split(":").every((d) => typeof values[d] != "undefined"))
+            .forEach((counter) => {
+            const missing = counter.split(":").filter((d) => typeof values[d] == "undefined");
+            console.warn(`MemoryStore<${this.key}>.incCounters WARNING: skipping counter "${counter}": missing dimension(s) ${missing.join(", ")} in values`, { values });
+        });
+        counters
+            .filter((counter) => counter.split(":").every((d) => typeof values[d] != "undefined"))
+            .forEach((counter) => {
+            const member = counter.split(":").map((d) => `${d}=${values[d]}`).join(":");
+            [
+                [`${this.key}Totals:${counter}`, delta.total],
+                [`${this.key}Counts:${counter}`, delta.count],
+            ].forEach(([setKey, d]) => {
+                if (!this.counters.has(setKey))
+                    this.counters.set(setKey, new Map());
+                const counterMap = this.counters.get(setKey);
+                counterMap.set(member, (counterMap.get(member) || 0) + d);
+            });
+        });
+    }
+    async queryCounter(kind, counter, exact, range) {
+        this.debug && console.log(`MemoryStore<${this.key}>.queryCounter`, { kind, counter, exact, range });
+        const dims = counter.split(":");
+        const setKey = `${this.key}${kind == "totals" ? "Totals" : "Counts"}:${counter}`;
+        const counterMap = this.counters.get(setKey) || new Map();
+        const prefix = dims
+            .filter((d) => typeof exact[d] != "undefined")
+            .map((d) => `${d}=${exact[d]}`)
+            .join(":");
+        const hasMore = dims.length > Object.keys(exact).length;
+        const minPrefix = (range === null || range === void 0 ? void 0 : range.min) != null ? `${prefix}${prefix ? ":" : ""}${range.field}=${range.min}` : prefix;
+        const maxPrefix = (range === null || range === void 0 ? void 0 : range.max) != null ? `${prefix}${prefix ? ":" : ""}${range.field}=${range.max}` : prefix;
+        // matches RedisStore's `[`-prefixed (always inclusive) ZRANGEBYLEX bounds, minus the
+        // Redis-specific bound-type marker -- comparisons below are plain string comparisons.
+        const min = `${minPrefix}${hasMore ? ":\x00" : ""}`;
+        const max = `${maxPrefix}${hasMore ? ":\x7f" : ""}`;
+        this.debug && console.log(`MemoryStore<${this.key}>.queryCounter`, { setKey, min, max });
+        // sorted lexicographically to mirror ZRANGEBYLEX's byte-order member comparison
+        const members = Array.from(counterMap.keys()).sort();
+        const filtered = members.filter((m) => m >= min && m <= max);
+        if (kind == "count") {
+            this.debug && console.log(`MemoryStore<${this.key}>.queryCounter`, { count: filtered.length });
+            return filtered.length;
+        }
+        const results = filtered.map((member) => ({ member, score: counterMap.get(member) }));
+        this.debug && console.log(`MemoryStore<${this.key}>.queryCounter`, { results });
+        return results;
+    }
+    async delete(id, options) {
+        this.debug && console.log(`MemoryStore<${this.key}>.delete`, { id, options });
+        if (!id) {
+            throw `Cannot delete ${this.key}: null id`;
+        }
+        options = { ...this.options, ...options };
+        const value = await this.get(id, { deleted: true });
+        if (!value) {
+            console.warn(`MemoryStore<${this.key}>.delete WARNING: does not exist: ${id}`);
+        }
+        const lookupKeys = value && this.lookupKeys(value, options);
+        this.debug && console.log(`MemoryStore<${this.key}>.delete`, { lookupKeys });
+        const deletedAt = Date.now();
+        if (value) {
+            if (options === null || options === void 0 ? void 0 : options.hardDelete) {
+                this.records.delete(id);
+            }
+            else {
+                this.records.set(id, { ...value, deletedAt });
+            }
+        }
+        this.index.remove(id);
+        (lookupKeys || []).forEach(([lookupKey, lookupId]) => { var _a; return (_a = this.lookups.get(lookupKey)) === null || _a === void 0 ? void 0 : _a.remove(lookupId); });
+        return value ? { ...value, deletedAt } : undefined;
+    }
+}
+exports.default = MemoryStore;

package/dist/store.d.ts

@@ -0,0 +1,37 @@
+import type { RedisStoreRecord } from "./index";
+export interface Store<T extends RedisStoreRecord> {
+    key: string;
+    setKey: string;
+    options: any;
+    debug: boolean;
+    exists(id: string): Promise<boolean>;
+    get(id: string, options?: any): Promise<T | undefined>;
+    scan(query?: any): Promise<Set<string>>;
+    ids(query?: any): Promise<Set<string>>;
+    find(query?: any): Promise<T[]>;
+    create(value: any, options?: {
+        expire?: number;
+        noIndex?: boolean;
+        score?: number;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T>;
+    update(value: any, options?: any): Promise<T>;
+    incCounters(values: Record<string, string | number>, delta: {
+        total: number;
+        count: number;
+    }): Promise<any>;
+    queryCounter(kind: "count" | "counts" | "totals", counter: string, exact: Record<string, string | number>, range?: {
+        field: string;
+        min?: string;
+        max?: string;
+    }): Promise<number | Array<{
+        member: string;
+        score: number;
+    }>>;
+    delete(id: string, options?: {
+        hardDelete?: boolean;
+        noLookup?: boolean;
+        lookups?: any;
+    }): Promise<T | undefined>;
+}

package/dist/store.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desmat/redis-store",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -13,7 +13,9 @@
   ],
   "scripts": {
     "build": "tsc",
-    "example": "ts-node --skipProject ./src/example.ts"
+    "prepare": "tsc",
+    "example": "ts-node --skipProject ./src/example.ts",
+    "test": "tsx --test test/**/*.test.ts"
   },
   "repository": {
     "type": "git",
@@ -30,11 +32,12 @@
   "license": "MIT",
   "dependencies": {
     "@desmat/utils": "^1.0.0",
-    "@upstash/redis": "^1.34.3",
+    "@upstash/redis": "^1.38.0",
     "dotenv": "^16.4.5"
   },
   "devDependencies": {
     "@types/node": "^22.8.4",
+    "tsx": "^4.21.0",
     "typescript": "^4.0.0"
   }
 }