@desmat/redis-store 1.0.1 → 1.0.4

package/README.md

@@ -1,30 +1,173 @@
-# redis-store
-A lightweight wrapper for using Redis as a data store
+# @desmat/redis-store
 
-## To build
+[![NPM Version](https://img.shields.io/npm/v/%40desmat%2Fredis-store?link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40desmat%2Futils)](https://www.npmjs.com/package/@desmat/redis-store)
+[![license](https://img.shields.io/npm/l/@desmat/utils?link=LICENSE)](LICENSE)
+
+A lightweight library to facilitate using the (in)famously fast in-memory database as your primary data store for your app’s entities and their relationships.
+
+Leans into Redis’ strong suits to bring relational aspects to the simple but performant KV store:
+- Lots of small read/writes
+- JSON keys for storing entities (no migration scripts required)
+- ZSET keys to track lists and relations
+
+Plays well with Upstash and Vercel but will work with any Redis instance via REST API.
+
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install @desmat/redis-store
 ```
-npm run build
+
+Or with Yarn:
+
+```bash
+yarn add @yourusername/redis-store
 ```
 
-## Example
-File `./src/example.ts` demonstrates simple use of this library.
 
-### To run:
+## Getting Started
 
-Create `.env` file with:
-```
+Below shows a simple schema with users and things belonging to users, some data added then queried. 
+
+`npm run example` to run [example.ts](./src/example.ts).
+
+
+### Setup environment variables
+
+```bash
+# your .env file, or provided in launch command
 KV_REST_API_URL=*****
-KV_REST_API_TOKEN=****
+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:
+*Note: Using Vercel KV environment variables enables this library to be used without friction on Vercel's platform, but `url` and `token` values can be provided in code.*
+
+### Setup entities and store
+
+```typescript
+import RedisStore from '@desmat/redis-store';
+
+type User = {
+ id: string, // required; set by .create as short UUID by default, or can be provided
+ createdAt: number, // required; set by .create
+ name: string,
+};
+
+type Thing = {
+ id: string,
+ createdAt: number,
+ createdBy: string, // required to lookup Things by Users
+ label: string,
+};
+
+const ThingOptions = {
+ lookups: {
+   user: "createdBy", // enables .find({ user: <USERID> })
+ },
+};
+
+// with environment variables `KV_REST_API_URL` and `KV_REST_API_TOKEN`
+// otherwise `url` and `token` can be provided to `RedisStore` constructor
+const store = {
+ users: new RedisStore<User>({ key: "user" }),
+ things: new RedisStore<Thing>({ key: "thing", options: ThingOptions }),
+};
 ```
-npm run example
+
+### Create users and things
+
+```typescript
+const users = await Promise.all([
+ store.users.create({ name: "User One" }),
+ store.users.create({ name: "User Two" }),
+]);
+
+// users (2): [
+//   { id: '<UUID>', createdAt: <TIMEINMILLIS>, name: 'User One' },
+//   ...
+// ]
+
+// Redis commands executed:
+//
+// JSON.SET user:<UUID> $ '{ "id": "<UUID>", "createdAt": <TIMEINMILLIS>, "name": "User One" }'
+// ZADD users <TIMEINMILLIS> <UUID>
+// ...
+
+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",
+ }),
+]);
+
+// things (4): [
+//   {
+//     id: '<UUID>',
+//     createdAt: <TIMEINMILLIS>,
+//     createdBy: '<USER_UUID>',
+//     label: 'A thing for user one'
+//   },
+//   ...
+// ]
+
+// Redis commands executed:
+//
+// 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>
+// ...
 ```
 
-### Or alternatively:
+### Query things
+
+```typescript
+const allThings = await store.things.find(); // 4 entries
+
+// Redis commands executed:
+//
+// ZRANGE things:user:<USER_UUID> 0 -1 REV
+// JSON.MGET thing:<THING1_UUID> thing:<THING2_UUID> ...
 
+const latestUserThings = await store.things.find({
+ user: users[0].id
+}); // 3 entries
+
+// Redis commands executed:
+//
+// ZRANGE things:user:<UUID> 0 -1 REV
+// JSON.MGET thing:<THING1_UUID> thing:<THING2_UUID> thing:<THING3_UUID>
 ```
-export KV_REST_API_URL=***** KV_REST_API_TOKEN=***** && npm run example
+
+### Cleanup (soft delete by default)
+
+```typescript
+await Promise.all([
+ ...users.map((user: User) => store.users.delete(user.id)),
+ ...things.map((thing: Thing) => store.things.delete(thing.id)),
+]);
+
+// Redis commands executed:
+//
+// 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/example.js

@@ -1,93 +1,28 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const index_1 = require("./index");
+const index_1 = __importDefault(require("./index"));
 require('dotenv').config();
-const ThingRecordOptions = {
+const ThingOptions = {
     lookups: {
         user: "createdBy", // enable .find({ user: <USERID> })
     },
 };
+// with environment variables KV_REST_API_URL and KV_REST_API_TOKEN
+// or `url` and `token` keys provided to RedisStore constructor
 const store = {
-    users: new index_1.RedisStore({
-        key: "user",
-        options: { hardDelete: false },
-    }),
-    things: new index_1.RedisStore({
-        key: "thing",
-        options: {
-            ...ThingRecordOptions,
-            hardDelete: false
-        }
-    }),
+    users: new index_1.default({ key: "user" }),
+    haikuUsers: new index_1.default({ key: "haikuuser" }),
+    userHaikus: new index_1.default({ key: "userhaiku" }),
+    // things: new RedisStore<Thing>({ key: "thing", options: ThingOptions }),
 };
 (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)),
+    const [users, haikuUsers, userHaikus] = await Promise.all([
+        store.users.ids({ scan: "*", count: 999999 }),
+        store.haikuUsers.ids({ scan: "*", count: 999999 }),
+        store.userHaikus.ids({ scan: "*", count: 999999 }),
     ]);
-    // JSON.SET user:<UUID> $.deletedAt <TIMEINMILLIS>
-    // ZREM users <UUID>
-    // ...
-    // JSON.SET thing:<UUID> $.deletedAt <TIMEINMILLIS>
-    // ZREM things <UUID>
-    // ZREM testthings:user:<USER_UUID> <UUID>
-    // ...
+    console.log("counts", { users: users.size, haikuUsers: haikuUsers.size, userHaikus: userHaikus.size });
 })();

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type RedisStoreRecord = {
     updatedAt?: number;
     deletedAt?: number;
 };
-export declare class RedisStore<T extends RedisStoreRecord> {
+export default class RedisStore<T extends RedisStoreRecord> {
     redis: Redis;
     key: string;
     setKey: string;

package/dist/index.js

@@ -19,15 +19,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RedisStore = void 0;
 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, options, debug, }) {
+        const _url = url || process.env.KV_REST_API_URL;
+        const _token = token || process.env.KV_REST_API_TOKEN;
+        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 || process.env.KV_REST_API_URL,
-            token: token || process.env.KV_REST_API_TOKEN
+            url: _url,
+            token: _token
         });
         this.key = key;
         this.setKey = setKey || key + "s";
@@ -275,4 +280,4 @@ class RedisStore {
         return value ? { ...value, deletedAt } : undefined;
     }
 }
-exports.RedisStore = RedisStore;
+exports.default = RedisStore;

package/dist/scratchpad.d.ts

@@ -0,0 +1,38 @@
+declare let RedisStore: any;
+declare let moment: typeof moment;
+declare let debug: boolean;
+type User = {
+    id: string;
+    createdAt: number;
+    name: string;
+} | any;
+type Post = {
+    id: string;
+    createdAt: number;
+    createdBy: string;
+    message: string;
+} | any;
+declare let PostOptions: {
+    lookups: {
+        user: string;
+    };
+};
+type UserPost = {
+    id: string;
+    createdAt: number;
+    userId: string;
+    postId: string;
+    viewedAt: number;
+    likedAt: number;
+} | any;
+declare let UserPostOptions: {
+    lookups: {
+        user: string;
+        post: string;
+    };
+};
+declare let store: {
+    users: any;
+    posts: any;
+    userPosts: any;
+};

package/dist/scratchpad.js

@@ -0,0 +1,118 @@
+"use strict";
+let RedisStore = require("./index");
+// @ts-ignore
+let moment = require("moment");
+require('dotenv').config();
+let debug = false;
+let PostOptions = {
+    lookups: {
+        user: "createdBy",
+    },
+};
+let UserPostOptions = {
+    lookups: {
+        user: "userId",
+        post: "postId",
+    },
+};
+console.log(RedisStore);
+let store = {
+    users: new RedisStore({ key: "testuser", debug }),
+    posts: new RedisStore({ key: "testpost", options: PostOptions, debug }),
+    userPosts: new RedisStore({ key: "testuserpost", options: UserPostOptions, debug }),
+};
+(async function () {
+    // new user signs up
+    let users = await Promise.all([
+        store.users.create({ name: "User One" }),
+        store.users.create({ name: "User Two" }),
+        store.users.create({ name: "User Three" }),
+    ]);
+    console.log("\n=== Users ===");
+    users.forEach((user) => {
+        console.log(`[user ${user.id}]: ${user.name}`);
+    });
+    // users creates posts
+    let 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
+    let latestPosts = await store.posts.find({ user: users[0].id, count: 3 });
+    console.log("\n=== Latest posts ===");
+    latestPosts.forEach((post) => {
+        console.log(`[post ${post.id}]: ${post.message}`);
+    });
+    // users views posts 
+    let userPosts = await Promise.all([
+        // createdAt will record post views
+        store.userPosts.create({
+            id: `${users[1].id}:${posts[0].id}`,
+            userId: users[1].id,
+            postId: posts[0].id,
+        }),
+        store.userPosts.create({
+            id: `${users[1].id}:${posts[1].id}`,
+            userId: users[1].id,
+            postId: posts[1].id,
+        }),
+        // record that this user liked this post
+        store.userPosts.create({
+            id: `${users[2].id}:${posts[1].id}`,
+            userId: users[2].id,
+            postId: posts[1].id,
+            likedAt: moment().valueOf(),
+        }),
+    ]);
+    // a user likes a post
+    userPosts[2] = await store.userPosts.update({
+        ...userPosts[2],
+        likedAt: moment().valueOf(),
+    });
+    // load all of a user's viewed posts
+    console.log("\n=== A user's viewed posts ===");
+    let 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("\n=== A post's views and likes ===");
+    let 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) => store.users.delete(user.id, { hardDelete: true })),
+        ...posts.map((post) => store.posts.delete(post.id, { hardDelete: true })),
+        ...userPosts.map((userPost) => store.userPosts.delete(userPost.id, { hardDelete: true })),
+    ]);
+    // cleanup all from previous session
+    // let [usersToDelete, postsToDelete, userPostsToDelete] = await Promise.all([
+    //   store.users.ids({ scan: "*" }),
+    //   store.posts.ids({ scan: "*" }),
+    //   store.userPosts.ids({ scan: "*" }),
+    // ])
+    // console.log("users to delete", { usersToDelete, postsToDelete, userPostsToDelete });
+    // await Promise.all([
+    //   // @ts-ignore
+    //   ...Array.from(usersToDelete).map((id: string) => store.users.delete(id, { hardDelete: true })),
+    //   // @ts-ignore
+    //   ...Array.from(postsToDelete).map((id: string) => store.posts.delete(id, { hardDelete: true })),
+    //   // @ts-ignore
+    //   ...Array.from(userPostsToDelete).map((id: string) => store.userPosts.delete(id, { hardDelete: true })),
+    // ]);
+    console.log(store.users.redis);
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desmat/redis-store",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -13,14 +13,13 @@
   ],
   "scripts": {
     "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"
+    "example": "ts-node --skipProject ./src/example.ts"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/desmat/redis-store.git"
   },
+  "homepage": "https://www.npmjs.com/package/@desmat/redis-store",
   "keywords": [
     "utility",
     "library",