@desmat/redis-store 1.0.1 → 1.0.2

package/README.md

@@ -1,30 +1,160 @@
-# redis-store
-A lightweight wrapper for using Redis as a data store
+# @desmat/redis-store
 
-## To build
-```
-npm run build
-```
+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 a 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 any Redis instance supported via REST API.
+
+
+## Getting Started
+
+Below shows a simple schema with users and things belonging to users, some data added then queried. 
 
-## Example
-File `./src/example.ts` demonstrates simple use of this library.
+`npm run example` to run [example.ts](./src/example.ts).
 
-### To run:
+### Install the library into your project 
 
-Create `.env` file with:
+```bash 
+npm install @desmat/redis-store
 ```
+
+### 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,24 +1,20 @@
 "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" }),
+    things: new index_1.default({ key: "thing", options: ThingOptions }),
 };
 (async function () {
     // create users

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,7 +19,6 @@ 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");
@@ -275,4 +274,4 @@ class RedisStore {
         return value ? { ...value, deletedAt } : undefined;
     }
 }
-exports.RedisStore = RedisStore;
+exports.default = RedisStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desmat/redis-store",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -13,9 +13,7 @@
   ],
   "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",