@desmat/redis-store 1.0.0 → 1.0.1

package/README.md

@@ -2,4 +2,29 @@
 A lightweight wrapper for using Redis as a data store
 
 ## To build
-`npm run build`
+```
+npm run build
+```
+
+## Example
+File `./src/example.ts` demonstrates simple use of this library.
+
+### To run:
+
+Create `.env` file with:
+```
+KV_REST_API_URL=*****
+KV_REST_API_TOKEN=****
+```
+*Note: Using Vercel KV environment variables enables this library to be used without friction on Vercel's platform, but can be overwritten programmatically.*
+
+then:
+```
+npm run example
+```
+
+### Or alternatively:
+
+```
+export KV_REST_API_URL=***** KV_REST_API_TOKEN=***** && npm run example
+```

package/dist/example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+require('dotenv').config();
+const ThingRecordOptions = {
+    lookups: {
+        user: "createdBy", // enable .find({ user: <USERID> })
+    },
+};
+const store = {
+    users: new index_1.RedisStore({
+        key: "user",
+        options: { hardDelete: false },
+    }),
+    things: new index_1.RedisStore({
+        key: "thing",
+        options: {
+            ...ThingRecordOptions,
+            hardDelete: false
+        }
+    }),
+};
+(async function () {
+    // create users
+    const users = await Promise.all([
+        store.users.create({ name: "User One" }),
+        store.users.create({ name: "User Two" }),
+    ]);
+    // Redis commands executed:
+    // JSON.SET user:<UUID> $ '{ "id": "<UUID>", "createdAt": <TIMEINMILLIS>, "name": "User One" }'
+    // ZADD users <TIMEINMILLIS> <UUID>
+    // ...
+    console.log("users", users);
+    // users (2 entries): [
+    //   { id: '<UUID>', createdAt: <TIMEINMILLIS>, name: 'User One' },
+    //   ...
+    // ]
+    // create things
+    const things = await Promise.all([
+        store.things.create({
+            createdBy: users[0].id,
+            label: "A thing for user one",
+        }),
+        store.things.create({
+            createdBy: users[0].id,
+            label: "Another thing for user one",
+        }),
+        store.things.create({
+            createdBy: users[0].id,
+            label: "Yet another thing for user one",
+        }),
+        store.things.create({
+            createdBy: users[1].id,
+            label: "A thing for user two",
+        }),
+    ]);
+    // JSON.SET thing:<UUID> $ '{ "id": "<UUID>", "createdAt": <TIMEINMILLIS>, "createdBy": "<USER_UUID>", "message": "Another thing for user one" }'
+    // ZADD things <TIMEINMILLIS> <UUID>
+    // ZADD things:user:<USER_UUID> <TIMEINMILLIS> <UUID>
+    // ... 
+    console.log("things", things);
+    // things (4 entries): [
+    //   {
+    //     id: '<UUID>',
+    //     createdAt: <TIMEINMILLIS>,
+    //     createdBy: '<USER_UUID>',
+    //     label: 'A thing for user one'
+    //   },
+    //   ...
+    // ]
+    // all things
+    const allThings = await store.things.find();
+    // ZRANGE	things:user:<USER_UUID> 0 -1 REV
+    // JSON.MGET thing:<THING1_UUID> thing:<THING2_UUID> ...
+    console.log("allThings", allThings); // 4 entries
+    // latest things from first user
+    const latestUserThings = await store.things.find({ user: users[0].id });
+    // ZRANGE	things:user:<USER_UUID> 0 -1 REV
+    // JSON.MGET thing:<THING1_UUID> thing:<THING2_UUID> thing:<THING3_UUID>
+    console.log("latestUserThings", latestUserThings); // 3 entries
+    // cleanup from this session (soft delete by default)
+    await Promise.all([
+        ...users.map((user) => store.users.delete(user.id)),
+        ...things.map((thing) => store.things.delete(thing.id)),
+    ]);
+    // JSON.SET user:<UUID> $.deletedAt <TIMEINMILLIS>
+    // ZREM users <UUID>
+    // ...
+    // JSON.SET thing:<UUID> $.deletedAt <TIMEINMILLIS>
+    // ZREM things <UUID>
+    // ZREM testthings:user:<USER_UUID> <UUID>
+    // ...
+})();

package/dist/index.d.ts

@@ -10,23 +10,23 @@ export declare class RedisStore<T extends RedisStoreRecord> {
     key: string;
     setKey: string;
     valueKey: (id: string) => string;
-    recordOptions: any;
+    options: any;
     debug: boolean;
-    constructor({ url, token, key, setKey, recordOptions, debug, }: {
-        url: string;
-        token: string;
+    constructor({ url, token, key, setKey, options, debug, }: {
         key: string;
         setKey?: string;
-        recordOptions?: any;
+        options?: any;
+        url?: string;
+        token?: string;
         debug?: boolean;
     });
     lookupKeys(value: any, options?: any): any[][];
     exists(id: string): Promise<boolean>;
-    get(id: string): Promise<T | undefined>;
+    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>;
     update(value: any, options?: any): Promise<T>;
-    delete(id: string, options?: any): Promise<T>;
+    delete(id: string, options?: any): Promise<T | undefined>;
 }

package/dist/index.js

@@ -24,16 +24,19 @@ const moment_1 = __importDefault(require("moment"));
 const utils_1 = require("@desmat/utils");
 const redis_1 = require("@upstash/redis");
 class RedisStore {
-    constructor({ url, token, key, setKey, recordOptions, debug, }) {
-        this.redis = new redis_1.Redis({ url, token });
+    constructor({ url, token, key, setKey, options, debug, }) {
+        this.redis = new redis_1.Redis({
+            url: url || process.env.KV_REST_API_URL,
+            token: token || process.env.KV_REST_API_TOKEN
+        });
         this.key = key;
         this.setKey = setKey || key + "s";
         this.valueKey = (id) => `${key}:${id}`;
-        this.recordOptions = recordOptions;
+        this.options = options;
         this.debug = !!debug;
     }
     lookupKeys(value, options) {
-        options = { ...this.recordOptions, ...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
@@ -82,19 +85,20 @@ class RedisStore {
         this.debug && console.log(`RedisStore<${this.key}>.exists`, { response });
         return response > 0;
     }
-    async get(id) {
+    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) {
+        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 });
-        const count = query.count;
+        !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";
@@ -170,7 +174,7 @@ class RedisStore {
             this.debug && console.log(`RedisStore<${this.key}>.find`, { keys });
         }
         // don't mget too many at once otherwise 💥
-        const blockSize = 512;
+        const blockSize = 256;
         const blocks = keys && keys.length && Array
             .apply(null, Array(Math.ceil(keys.length / blockSize)))
             .map((v, block) => (keys || [])
@@ -187,9 +191,9 @@ class RedisStore {
         return values;
     }
     async create(value, options) {
-        this.debug && console.log(`RedisStore<${this.key}>.create`, { value, options, recordOptions: this.recordOptions });
+        this.debug && console.log(`RedisStore<${this.key}>.create`, { value, options, this_options: this.options });
         const now = (0, moment_1.default)().valueOf();
-        options = { ...this.recordOptions, ...options };
+        options = { ...this.options, ...options };
         const createdValue = {
             id: value.id || (0, utils_1.uuid)(),
             createdAt: value.createdAt || now,
@@ -217,7 +221,7 @@ class RedisStore {
             throw `Cannot update ${this.key}: does not exist: ${value.id}`;
         }
         const now = (0, moment_1.default)().valueOf();
-        options = { ...this.recordOptions, ...options };
+        options = { ...this.options, ...options };
         const updatedValue = {
             ...value,
             updatedAt: now,
@@ -252,23 +256,23 @@ class RedisStore {
         if (!id) {
             throw `Cannot delete ${this.key}: null id`;
         }
-        options = { ...this.recordOptions, ...options };
-        const value = await this.get(id);
+        options = { ...this.options, ...options };
+        const value = await this.get(id, { deleted: true });
         if (!value) {
-            throw `Cannot update ${this.key}: does not exist: ${id}`;
+            console.warn(`RedisStore<${this.key}>.delete WARNING: does not exist: ${id}`);
         }
-        const lookupKeys = this.lookupKeys(value, options);
+        const lookupKeys = value && this.lookupKeys(value, options);
         this.debug && console.log(`RedisStore<${this.key}>.delete`, { lookupKeys });
-        value.deletedAt = (0, moment_1.default)().valueOf();
+        const deletedAt = (0, moment_1.default)().valueOf();
         const response = await Promise.all([
             options.hardDelete
                 ? this.redis.json.del(this.valueKey(id), "$")
-                : this.redis.json.set(this.valueKey(id), "$", { ...value, deletedAt: (0, moment_1.default)().valueOf() }),
+                : 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;
+        return value ? { ...value, deletedAt } : undefined;
     }
 }
 exports.RedisStore = RedisStore;

package/dist/repl.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/repl.js

@@ -0,0 +1,139 @@
+"use strict";
+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 index_1 = require("./index");
+const KV_REST_API_URL = "https://close-ringtail-23695.upstash.io";
+const KV_REST_API_TOKEN = "AVyPAAIjcDE4ZDhiZjAxNjU3NjI0NGU1YjIwMzAzNzkzMWRkMDU2ZHAxMA";
+const debug = false;
+const UserRecordOptions = {
+    lookups: {
+    // user: "createdBy",
+    },
+};
+const PostRecordOptions = {
+    lookups: {
+        user: "createdBy",
+    },
+};
+const UserPostRecordOptions = {
+    lookups: {
+        user: "userId",
+        post: "postId",
+    },
+};
+const store = {
+    users: new index_1.RedisStore({
+        url: KV_REST_API_URL,
+        token: KV_REST_API_TOKEN,
+        key: "testuser",
+        setKey: "testusers",
+        recordOptions: UserRecordOptions,
+        debug,
+    }),
+    posts: new index_1.RedisStore({
+        url: KV_REST_API_URL,
+        token: KV_REST_API_TOKEN,
+        key: "testpost",
+        setKey: "testposts",
+        recordOptions: PostRecordOptions,
+        debug,
+    }),
+    userPosts: new index_1.RedisStore({
+        url: KV_REST_API_URL,
+        token: KV_REST_API_TOKEN,
+        key: "testuserpost",
+        setKey: "testuserposts",
+        recordOptions: UserPostRecordOptions,
+        debug,
+    }),
+};
+(async function () {
+    // console.log("Hello!");
+    // new user signs up
+    const users = await Promise.all([
+        store.users.create({ name: "User One" }),
+        store.users.create({ name: "User Two" }),
+        store.users.create({ name: "User Three" }),
+    ]);
+    // users creates posts
+    const posts = await Promise.all([
+        store.posts.create({
+            createdBy: users[0].id,
+            message: "A post by user one",
+        }),
+        store.posts.create({
+            createdBy: users[0].id,
+            message: "Another post by user one",
+        }),
+        store.posts.create({
+            createdBy: users[0].id,
+            message: "Yet another post by user one",
+        }),
+        store.posts.create({
+            createdBy: users[1].id,
+            message: "A post by user two",
+        }),
+    ]);
+    // show latest posts from first user
+    const latestPosts = await store.posts.find({ user: users[0].id, count: 3 });
+    console.log("=== Latest posts ===");
+    latestPosts.forEach((post) => {
+        console.log(`[post ${post.id}]: ${post.message}`);
+    });
+    // users views posts 
+    const userPosts = await Promise.all([
+        store.userPosts.create({
+            id: `${users[1].id}:${posts[0].id}`,
+            userId: users[1].id,
+            postId: posts[0].id,
+            viewedAt: (0, moment_1.default)().valueOf(),
+        }),
+        store.userPosts.create({
+            id: `${users[1].id}:${posts[1].id}`,
+            userId: users[1].id,
+            postId: posts[1].id,
+            viewedAt: (0, moment_1.default)().valueOf(),
+        }),
+        store.userPosts.create({
+            id: `${users[2].id}:${posts[1].id}`,
+            userId: users[2].id,
+            postId: posts[1].id,
+            viewedAt: (0, moment_1.default)().valueOf(),
+        }),
+    ]);
+    // a user likes a post
+    userPosts[2] = await store.userPosts.update({
+        ...userPosts[2],
+        likedAt: (0, moment_1.default)().valueOf(),
+    });
+    // load all of a user's viewed posts
+    console.log("=== A user's viewed posts ===");
+    const userViewedPosts = await store.userPosts.find({ user: users[1].id });
+    userViewedPosts.forEach((userPost) => {
+        console.log(`[user ${userPost.userId}]: ${userPost.id}`);
+    });
+    // load a post's count of views and likes
+    console.log("=== A post's views and likes ===");
+    const postViews = await store.userPosts.find({ post: posts[1].id });
+    console.log(`[post ${posts[1].id}]: ${postViews.filter((userPost) => userPost.viewedAt).length} view(s) and ${postViews.filter((userPost) => userPost.likedAt).length} like(s)`);
+    // cleanup from this session
+    // await Promise.all([
+    //   ...users.map((user: User) => store.users.delete(user.id, { hardDelete: true })),
+    //   ...posts.map((post: Post) => store.posts.delete(post.id, { hardDelete: true })),
+    //   ...userPosts.map((userPost: UserPost) => store.userPosts.delete(userPost.id, { hardDelete: true })),
+    // ]);
+    // cleanup all from previous session
+    const [allUsers, allPosts, allUserPosts] = await Promise.all([
+        store.users.ids({ scan: "*", count: 999 }),
+        store.posts.ids({ scan: "*", count: 999 }),
+        store.userPosts.ids({ scan: "*", count: 999 }),
+    ]);
+    await Promise.all([
+        ...Array.from(allUsers).map((id) => store.users.delete(id, { hardDelete: true })),
+        ...Array.from(allPosts).map((id) => store.posts.delete(id, { hardDelete: true })),
+        ...Array.from(allUserPosts).map((id) => store.userPosts.delete(id, { hardDelete: true })),
+    ]);
+})();

package/dist/simple-example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/simple-example.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const KV_REST_API_URL = "https://close-ringtail-23695.upstash.io";
+const KV_REST_API_TOKEN = "AVyPAAIjcDE4ZDhiZjAxNjU3NjI0NGU1YjIwMzAzNzkzMWRkMDU2ZHAxMA";
+const debug = false;
+const PostRecordOptions = {
+    lookups: {
+        user: "createdBy",
+    },
+};
+const store = {
+    users: new index_1.RedisStore({
+        url: KV_REST_API_URL,
+        token: KV_REST_API_TOKEN,
+        key: "testuser",
+        debug,
+    }),
+    posts: new index_1.RedisStore({
+        url: KV_REST_API_URL,
+        token: KV_REST_API_TOKEN,
+        key: "testpost",
+        // recordOptions: PostRecordOptions,
+        debug,
+    }),
+};
+(async function () {
+    // create users
+    const users = await Promise.all([
+        store.users.create({ name: "User One" }),
+        store.users.create({ name: "User Two" }),
+    ]);
+    // JSON.SET user:<UUID> $ '{ "id": "<UUID>", "createdAt": <TIMEINMILLIS>, "name": "User One" }'
+    // ZADD users <TIMEINMILLIS> <UUID>
+    // ...
+    console.log("users", users);
+    // users [
+    //   { id: '<UUID>', createdAt: <TIMEINMILLIS>, name: 'User One' },
+    //   ...
+    // ]
+    // create posts
+    const posts = await Promise.all([
+        store.posts.create({
+            createdBy: users[0].id,
+            message: "A post by user one",
+        }),
+        store.posts.create({
+            createdBy: users[0].id,
+            message: "Another post by user one",
+        }),
+        store.posts.create({
+            createdBy: users[0].id,
+            message: "Yet another post by user one",
+        }),
+        store.posts.create({
+            createdBy: users[1].id,
+            message: "A post by user two",
+        }),
+    ]);
+    // JSON.SET post:<UUID> $ '{ "id": "<UUID>", "createdAt": <TIMEINMILLIS>, "createdBy": "<USER_UUID>", "message": "Another post by user one" }'
+    // ZADD posts <TIMEINMILLIS> <UUID>
+    // ZADD posts:user:<USER_UUID> <TIMEINMILLIS> <POST_UUID>
+    // ... 
+    console.log("posts", posts);
+    // posts [
+    //   {
+    //     id: '<UUID>',
+    //     createdAt: <TIMEINMILLIS>,
+    //     createdBy: '<USER_UUID>',
+    //     message: 'A post by user one'
+    //   },
+    //   ...
+    // ]
+    // all posts
+    const allPosts = await store.posts.find();
+    // ZRANGE	posts:user:<USER_UUID> 0 -1 REV
+    // JSON.MGET post:<POST1_UUID> post:<POST2_UUID> ...
+    // latest posts from first user
+    const latestUserPosts = await store.posts.find({ user: users[0].id, count: 3 });
+    // ZRANGE	posts:user:<USER_UUID> 0 2 REV
+    // JSON.MGET post:<POST1_UUID> post:<POST2_UUID> post:<POST3_UUID>
+    // cleanup from this session (soft delete by default)
+    await Promise.all([
+        ...users.map((user) => store.users.delete(user.id)),
+        ...posts.map((post) => store.posts.delete(post.id)),
+    ]);
+    // JSON.SET user:<UUID> $.deletedAt <TIMEINMILLIS>
+    // ZREM users <UUID>
+    // ...
+    // JSON.SET post:<POST_UUID> $.deletedAt <TIMEINMILLIS>
+    // ZREM posts <POST_UUID>
+    // ZREM testposts:user:<USER_UUID> <POST_UUID>
+    // ...
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desmat/redis-store",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -12,7 +12,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "example": "ts-node --skipProject ./src/example.ts",
+    "repl": "ts-node --skipProject -i -e 'console.log(\"Exec `.load ./scratchpad.ts` to run load a starter environment; Ctrl-D or Ctrl-C twice to exit.\")'",
+    "scratchpad": "ts-node --skipProject ./scratchpad.ts"
   },
   "repository": {
     "type": "git",
@@ -28,9 +31,11 @@
   "license": "MIT",
   "dependencies": {
     "@desmat/utils": "^1.0.0",
-    "@upstash/redis": "^1.34.3"
+    "@upstash/redis": "^1.34.3",
+    "dotenv": "^16.4.5"
   },
   "devDependencies": {
+    "@types/node": "^22.8.4",
     "typescript": "^4.0.0"
   }
-}
+}