feat: add type-safe keyspaces

This feature allows you to constrain the set of valid keys in a “keyspace” (a namespace of keys). This is especially useful if the keys should have a specific format or if only a finite set of keys are valid.

    enum Robot {
      Butler,
      Gardener,
    }

    enum Power {
      On = "on",
      Off = "off",
    }

    const robot = new RedisEntity(
      new RedisKeyspace<Robot>("robot-configuration"),
      Type.Enum(Power),
    );

    // You must qualify which robot you're setting the power for.
    // TypeScript will enforce this.
    SET(robot.qualify(Robot.Butler), Power.On);

Author: aleclarson

src/channel.ts

@@ -1,6 +1,6 @@
 import { TSchema, TString, Type } from "@sinclair/typebox";
 import { isString } from "radashi";
-import { RedisKey } from "./key";
+import { RedisKey, RedisKeyspace } from "./key";
 import { MessageEvent } from "./subscriber";
 import { RedisTransform } from "./transform";
 
@@ -9,23 +9,31 @@ import { RedisTransform } from "./transform";
  */
 export class RedisChannel<
   T extends TSchema = TSchema,
+  K extends string | RedisKeyspace = string,
 > extends RedisTransform<T> {
   declare $$typeof: "RedisChannel";
   constructor(
-    readonly name: string,
+    readonly name: K,
     schema: T,
   ) {
     super(schema);
   }
 
   /**
-   * Derive a subchannel by prefixing the current channel with the given
-   * keys. When multiple keys are passed in, they will be joined with a
-   * colon.
+   * Creates a new channel within a namespace.
    */
-  join(...keys: (string | number)[]) {
-    if (keys.length === 0) return this;
-    return new RedisChannel(`${this.name}:${keys.join(":")}`, this.schema);
+  qualify(
+    name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+  ): RedisChannel<T, string>;
+  qualify<T extends TSchema>(
+    name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    schema: T,
+  ): RedisChannel<T, string>;
+  qualify(
+    name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    schema: TSchema = this.schema,
+  ) {
+    return new RedisChannel<any>(`${this.name}:${name}`, schema);
   }
 
   /**
@@ -62,7 +70,7 @@ export class RedisChannelPattern<
  * [1]: https://redis.io/docs/latest/develop/use/keyspace-notifications/
  */
 export class RedisKeyspacePattern extends RedisChannelPattern<TString> {
-  constructor(pattern: string | RedisKey, database?: number) {
+  constructor(pattern: string | RedisKey | RedisKeyspace, database?: number) {
     super(
       `__keyspace@${database ?? "*"}__:${isString(pattern) ? pattern : pattern.name}`,
       Type.String(),

src/commands/read.ts

@@ -1,21 +1,21 @@
 import { StaticEncode, TSchema } from "@sinclair/typebox";
 import { RedisCommand } from "../command";
-import { RedisKey } from "../key";
+import { RedisEntity } from "../key";
 import { RedisModifier } from "../modifier";
 
 /** Return the previous value stored at this key */
 export type GET = RedisModifier<"GET">;
 
 /** Get the value of a key */
 export function GET<T extends TSchema>(
-  key: RedisKey<T>,
+  key: RedisEntity<T>,
 ): RedisCommand<StaticEncode<T> | undefined>;
 
 /** Return the previous value stored at this key */
 export function GET(): GET;
 
 export function GET<T extends TSchema>(
-  key?: RedisKey<T>,
+  key?: RedisEntity<T>,
 ): GET | RedisCommand<StaticEncode<T> | undefined> {
   if (!key) {
     return new RedisModifier("GET");

src/commands/write.ts

@@ -1,6 +1,6 @@
 import { StaticEncode, TNumber, TSchema } from "@sinclair/typebox";
 import { RedisCommand } from "../command";
-import { RedisKey } from "../key";
+import { RedisEntity, RedisKey } from "../key";
 import { encodeModifiers, Modifiers, Require } from "../modifier";
 import {
   EX,
@@ -31,7 +31,7 @@ export function FLUSHALL(mode?: "sync" | "async") {
  * expired, the key will automatically be deleted.
  */
 export function EXPIRE(
-  key: RedisKey<any>,
+  key: RedisKey,
   timeout: number,
   ...modifiers: Modifiers<[XX | NX | GT | LT]>
 ) {
@@ -46,7 +46,7 @@ export function EXPIRE(
  * similar to {@link GET}, but is a write command with additional options.
  */
 export function GETEX<T extends TSchema>(
-  key: RedisKey<T>,
+  key: RedisEntity<T>,
   ...modifiers: Modifiers<[EX | PX | EXAT | PXAT | PERSIST]>
 ) {
   return new RedisCommand<StaticEncode<T> | undefined>(
@@ -59,22 +59,22 @@ export function GETEX<T extends TSchema>(
  * Set the value of a key and optionally set its expiration.
  */
 export function SET<T extends TSchema>(
-  key: RedisKey<T>,
+  key: RedisEntity<T>,
   value: StaticEncode<T>,
   ...modifiers: Modifiers<
     [NX | XX, Require<GET>, EX | PX | EXAT | PXAT | KEEPTTL]
   >
 ): RedisCommand<StaticEncode<T> | undefined>;
 
 export function SET<T extends TSchema>(
-  key: RedisKey<T>,
+  key: RedisEntity<T>,
   value: StaticEncode<T>,
   ...modifiers: Modifiers<[NX | XX, EX | PX | EXAT | PXAT | KEEPTTL]>
 ): RedisCommand<boolean>;
 
 export function SET(
-  key: RedisKey<any>,
-  value: StaticEncode<any>,
+  key: RedisEntity,
+  value: unknown,
   ...modifiers: Modifiers
 ): RedisCommand<any> {
   return new RedisCommand(
@@ -95,27 +95,27 @@ export function DEL(...keys: [RedisKey, ...RedisKey[]]) {
 /**
  * Decrement the value of a key by 1.
  */
-export function DECR(key: RedisKey<TNumber>) {
+export function DECR(key: RedisEntity<TNumber>) {
   return new RedisCommand<number>(["DECR", key.name]);
 }
 
 /**
  * Decrement the value of a key by a specific amount.
  */
-export function DECRBY(key: RedisKey<TNumber>, amount: number) {
+export function DECRBY(key: RedisEntity<TNumber>, amount: number) {
   return new RedisCommand<number>(["DECRBY", key.name, amount]);
 }
 
 /**
  * Increment the value of a key by 1.
  */
-export function INCR(key: RedisKey<TNumber>) {
+export function INCR(key: RedisEntity<TNumber>) {
   return new RedisCommand<number>(["INCR", key.name]);
 }
 
 /**
  * Increment the value of a key by a specific amount.
  */
-export function INCRBY(key: RedisKey<TNumber>, amount: number) {
+export function INCRBY(key: RedisEntity<TNumber>, amount: number) {
   return new RedisCommand<number>(["INCRBY", key.name, amount]);
 }

src/key.ts

@@ -1,88 +1,139 @@
-import { StaticEncode, TSchema } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox/type";
+import { StaticEncode, TObject, TSchema } from "@sinclair/typebox/type";
 import { Decode, Encode } from "@sinclair/typebox/value";
 import { RedisValue } from "./command";
 import { RedisTransform } from "./transform";
 
-export type TRedisHash<TValue extends TSchema = TSchema> = Record<
-  string,
-  TValue
->;
-
-export type StaticHash<T extends TRedisHash> = {
-  [K in RedisField<T>]: StaticEncode<T[K]>;
-};
-
 /**
- * A field name of a Redis key that points to a hash map.
+ * Represents a namespace of keys in a Redis database.
  */
-export type RedisField<T extends TSchema | TRedisHash> = T extends TSchema
-  ? never
-  : Extract<keyof T, string>;
+export class RedisKeyspace<K extends string | number = string | number> {
+  declare $$typeof: "RedisKeyspace" & { K: K };
+  constructor(readonly name: string) {}
+
+  /**
+   * Creates a string pattern that matches all keys in the keyspace.
+   *
+   * You may pass this to the `RedisKeyspacePattern` constructor.
+   */
+  any() {
+    return `${this.name}:*` as const;
+  }
+}
 
 /**
- * A Redis key that points to a primitive value or a hash map.
+ * Represents a key in a Redis database with an unknown data structure. For
+ * example, it could be a primitive, hash, stream, etc.
  */
-export class RedisKey<
-  T extends TSchema | TRedisHash = TSchema | TRedisHash,
+export abstract class RedisKey<
+  T extends TSchema = TSchema,
+  K extends string | RedisKeyspace = string,
 > extends RedisTransform<T> {
   declare $$typeof: "RedisKey";
+
   constructor(
-    readonly name: string,
-    schema: T,
+    readonly name: K,
+    schema: T = Type.Unknown() as T,
   ) {
     super(schema);
   }
 
   /**
-   * Derive a new key by prefixing the current key with the given keys. When multiple keys are
-   * passed in, they will be joined with a colon.
+   * Creates a new key within a namespace.
    */
-  join(...keys: (string | number)[]): this {
-    if (keys.length === 0) return this;
-    return new (this.constructor as new (name: string, schema: T) => this)(
-      `${this.name}:${keys.join(":")}`,
-      this.schema,
-    );
-  }
+  qualify(
+    name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+  ): RedisKey<T, string>;
+  qualify<T extends TSchema>(
+    name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    schema: T,
+  ): RedisKey<T, string>;
+  qualify(
+    name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    schema: TSchema = this.schema,
+  ) {
+    const RedisKey = this.constructor as new (
+      name: string,
+      schema: TSchema,
+    ) => any;
 
-  /**
-   * Use this key as a namespace for a pattern. The `pattern` is appended
-   * to the current key with a colon between them.
-   */
-  match(pattern: string) {
-    return this.name + ":" + pattern;
+    return new RedisKey(`${this.name}:${name}`, schema);
   }
 }
 
-export class RedisSet<T extends TSchema = TSchema> extends RedisKey<T> {
+/**
+ * Represents a key in a Redis database with a single datum, like a
+ * primitive or a JSON object.
+ */
+export class RedisEntity<
+  T extends TSchema = TSchema,
+  K extends string | RedisKeyspace = string,
+> extends RedisKey<T, K> {
+  declare $$typeof: "RedisKey" & { subtype: "RedisEntity" };
+  declare qualify: {
+    (
+      name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    ): RedisEntity<T, string>;
+    <T extends TSchema>(
+      name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+      schema: T,
+    ): RedisEntity<T, string>;
+  };
+}
+
+export class RedisSet<
+  T extends TSchema = TSchema,
+  K extends string | RedisKeyspace = string,
+> extends RedisKey<T, K> {
   declare $$typeof: "RedisKey" & { subtype: "RedisSet" };
+  declare qualify: {
+    (
+      name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    ): RedisSet<T, string>;
+    <T extends TSchema>(
+      name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+      schema: T,
+    ): RedisSet<T, string>;
+  };
 }
 
-export class RedisHash<T extends TRedisHash = TRedisHash> extends RedisKey<T> {
+export class RedisHash<
+  T extends Record<string, TSchema> = Record<string, TSchema>,
+  K extends string | RedisKeyspace = string,
+> extends RedisKey<TObject<T>, K> {
   declare $$typeof: "RedisKey" & { subtype: "RedisHash" };
+  declare qualify: {
+    (
+      name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+    ): RedisHash<T, string>;
+    <T extends TSchema>(
+      name: K extends RedisKeyspace<infer Key> ? Key : string | number,
+      schema: T,
+    ): RedisHash<T, string>;
+  };
 
   /**
    * Like `encode`, but for keys that point to a hash map.
    */
-  encodeField<TField extends RedisField<T>>(
+  encodeField<TField extends keyof T>(
     field: TField,
     value: StaticEncode<T[TField]>,
   ): RedisValue {
     // The schema is defined for JS, not Redis, so a "decoded" value
     // represents a Redis value.
-    return Decode(this.schema[field], value) as any;
+    return Decode(this.schema.properties[field], value) as any;
   }
 
   /**
    * Like `decode`, but for keys that point to a hash map.
    */
-  decodeField<TField extends RedisField<T>>(
+  decodeField<TField extends keyof T>(
     field: TField,
     value: unknown,
-  ): T extends TSchema ? never : StaticEncode<T[TField]> {
+  ): StaticEncode<T[TField]> {
     // The schema is defined for JS, not Redis, so an "encoded" value
     // represents a JS value.
-    return Encode(this.schema[field], value);
+    return Encode(this.schema.properties[field], value);
   }
 }
 

src/stream.ts

@@ -6,7 +6,7 @@ import {
   TString,
 } from "@sinclair/typebox";
 import { RedisValue } from "./command";
-import { RedisTransform } from "./transform";
+import { RedisKey, RedisKeyspace } from "./key";
 
 /** Any valid schema for a Redis stream entry. */
 export type TRedisStreamEntry =
@@ -25,14 +25,9 @@ export type RedisStreamPosition<
 
 export class RedisStream<
   T extends TRedisStreamEntry = TRedisStreamEntry,
-> extends RedisTransform<T> {
-  declare $$typeof: "RedisStream";
-  constructor(
-    readonly name: string,
-    entrySchema: T,
-  ) {
-    super(entrySchema);
-  }
+  K extends string | RedisKeyspace = string,
+> extends RedisKey<T, K> {
+  declare $$typeof: "RedisKey" & { subtype: "RedisStream" };
 
   /**
    * For use with `XREAD` or `XREADGROUP`. Defines which ID was last delivered to the
@@ -59,7 +54,7 @@ export class RedisStreamEntry<T extends TRedisStreamEntry = TRedisStreamEntry> {
   readonly data: StaticEncode<T>;
   constructor(
     /** The stream this entry belongs to */
-    readonly stream: RedisStream<T>,
+    readonly stream: RedisStream<T, string>,
     /** The ID of this entry */
     readonly id: string,
     /** The fields and values of this entry */