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/hash.ts

@@ -1,32 +1,36 @@
-import { Static, StaticEncode } from "@sinclair/typebox";
+import { StaticEncode, TSchema } from "@sinclair/typebox";
 import { RedisCommand, RedisValue } from "../command";
-import { RedisField, RedisHash, TRedisHash } from "../key";
+import { RedisHash } from "../key";
+
+type RedisField<T extends Record<string, TSchema>> = keyof T & string;
 
 /**
  * Get the value of a field in a hash.
  */
-export function HGET<T extends TRedisHash, TField extends RedisField<T>>(
-  hash: RedisHash<T>,
-  field: TField,
-) {
-  return new RedisCommand<Static<T[TField]>>(
-    ["HGET", hash.name, field],
-    (result) => hash.decodeField(field, result),
+export function HGET<
+  T extends Record<string, TSchema>,
+  TField extends RedisField<T>,
+>(hash: RedisHash<T>, field: TField) {
+  return new RedisCommand(["HGET", hash.name, field as string], (result) =>
+    hash.decodeField(field, result),
   );
 }
 
 /**
  * Set the value of a field in a hash.
  */
-export function HSET<T extends TRedisHash, TField extends RedisField<T>>(
-  hash: RedisHash<T>,
-  field: TField,
-): never;
+export function HSET<
+  T extends Record<string, TSchema>,
+  TField extends RedisField<T>,
+>(hash: RedisHash<T>, field: TField): never;
 
 /**
  * Set the value of a field in a hash.
  */
-export function HSET<T extends TRedisHash, TField extends RedisField<T>>(
+export function HSET<
+  T extends Record<string, TSchema>,
+  TField extends RedisField<T>,
+>(
   hash: RedisHash<T>,
   field: TField,
   value: StaticEncode<T[TField]>,
@@ -35,12 +39,12 @@ export function HSET<T extends TRedisHash, TField extends RedisField<T>>(
 /**
  * Set the values of multiple fields in a hash.
  */
-export function HSET<T extends TRedisHash>(
+export function HSET<T extends Record<string, TSchema>>(
   hash: RedisHash<T>,
   values: { [K in RedisField<T>]?: StaticEncode<T[K]> },
 ): RedisCommand<number>;
 
-export function HSET<T extends TRedisHash>(
+export function HSET<T extends Record<string, TSchema>>(
   hash: RedisHash<T>,
   field: RedisField<T> | object,
   value?: unknown,
@@ -52,7 +56,7 @@ export function HSET<T extends TRedisHash>(
   );
 }
 
-function encodeHashEntries<T extends TRedisHash>(
+function encodeHashEntries<T extends Record<string, TSchema>>(
   hash: RedisHash<T>,
   values: object,
 ) {

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]);
 }