@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/search/schema-builder.ts

@@ -0,0 +1,320 @@
+import type { NestedIndexSchema, NumericField } from "./types";
+
+type TextFieldBuild<
+  TNoTokenize extends Record<"noTokenize", boolean>,
+  TNoStem extends Record<"noStem", boolean>,
+  TFrom extends Record<"from", string | null>,
+> = TNoTokenize["noTokenize"] extends true
+  ? { type: "TEXT"; noTokenize: true } & (TNoStem["noStem"] extends true
+      ? { noStem: true }
+      : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        {}) &
+      (TFrom["from"] extends string
+        ? { from: TFrom["from"] }
+        : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+          {})
+  : TNoStem["noStem"] extends true
+    ? { type: "TEXT"; noStem: true } & (TFrom["from"] extends string
+        ? { from: TFrom["from"] }
+        : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+          {})
+    : TFrom["from"] extends string
+      ? { type: "TEXT"; from: TFrom["from"] }
+      : { type: "TEXT" };
+
+// Internal symbol for build method
+const BUILD = Symbol("build");
+
+// Field builders with chainable options
+class TextFieldBuilder<
+  TNoTokenize extends Record<"noTokenize", boolean> = { noTokenize: false },
+  TNoStem extends Record<"noStem", boolean> = { noStem: false },
+  TFrom extends Record<"from", string | null> = { from: null },
+> {
+  private _noTokenize: TNoTokenize;
+  private _noStem: TNoStem;
+  private _from: TFrom;
+
+  constructor(
+    noTokenize = { noTokenize: false } as TNoTokenize,
+    noStem = { noStem: false } as TNoStem,
+    from = { from: null } as TFrom
+  ) {
+    this._noTokenize = noTokenize;
+    this._noStem = noStem;
+    this._from = from;
+  }
+
+  noTokenize(): TextFieldBuilder<{ noTokenize: true }, TNoStem, TFrom> {
+    return new TextFieldBuilder({ noTokenize: true }, this._noStem, this._from);
+  }
+
+  noStem(): TextFieldBuilder<TNoTokenize, { noStem: true }, TFrom> {
+    return new TextFieldBuilder(this._noTokenize, { noStem: true }, this._from);
+  }
+
+  from(field: string): TextFieldBuilder<TNoTokenize, TNoStem, { from: string }> {
+    return new TextFieldBuilder(this._noTokenize, this._noStem, { from: field } as {
+      from: string;
+    });
+  }
+
+  [BUILD](): TextFieldBuild<TNoTokenize, TNoStem, TFrom> {
+    return {
+      type: "TEXT",
+      ...(this._noTokenize.noTokenize ? { noTokenize: true } : {}),
+      ...(this._noStem.noStem ? { noStem: true } : {}),
+      ...(this._from.from ? { from: this._from.from } : {}),
+    } as any;
+  }
+}
+
+class NumericFieldBuilder<
+  T extends NumericField["type"],
+  TFrom extends Record<"from", string | null> = { from: null },
+> {
+  private type: T;
+  private _from: TFrom;
+
+  constructor(type: T, from = { from: null } as TFrom) {
+    this.type = type;
+    this._from = from;
+  }
+
+  from(field: string): NumericFieldBuilder<T, { from: string }> {
+    return new NumericFieldBuilder(this.type, { from: field } as { from: string });
+  }
+
+  [BUILD](): TFrom["from"] extends string
+    ? { type: T; fast: true; from: TFrom["from"] }
+    : { type: T; fast: true } {
+    return this._from.from
+      ? ({
+          type: this.type,
+          fast: true,
+          from: this._from.from,
+        } as any)
+      : ({
+          type: this.type,
+          fast: true,
+        } as any);
+  }
+}
+
+class BoolFieldBuilder<
+  Fast extends Record<"fast", boolean> = { fast: false },
+  TFrom extends Record<"from", string | null> = { from: null },
+> {
+  private _fast: Fast;
+  private _from: TFrom;
+
+  constructor(fast = { fast: false } as Fast, from = { from: null } as TFrom) {
+    this._fast = fast;
+    this._from = from;
+  }
+
+  fast(): BoolFieldBuilder<{ fast: true }, TFrom> {
+    return new BoolFieldBuilder({ fast: true }, this._from);
+  }
+
+  from(field: string): BoolFieldBuilder<Fast, { from: string }> {
+    return new BoolFieldBuilder(this._fast, { from: field } as { from: string });
+  }
+
+  [BUILD](): Fast extends { fast: true }
+    ? TFrom["from"] extends string
+      ? { type: "BOOL"; fast: true; from: TFrom["from"] }
+      : { type: "BOOL"; fast: true }
+    : TFrom["from"] extends string
+      ? { type: "BOOL"; from: TFrom["from"] }
+      : { type: "BOOL" } {
+    const hasFast = this._fast.fast;
+    const hasFrom = Boolean(this._from.from);
+
+    if (hasFast && hasFrom) {
+      return {
+        type: "BOOL",
+        fast: true,
+        from: this._from.from,
+      } as any;
+    }
+    if (hasFast) {
+      return {
+        type: "BOOL",
+        fast: true,
+      } as any;
+    }
+    if (hasFrom) {
+      return {
+        type: "BOOL",
+        from: this._from.from,
+      } as any;
+    }
+    return { type: "BOOL" } as any;
+  }
+}
+
+class DateFieldBuilder<
+  Fast extends Record<"fast", boolean> = { fast: false },
+  TFrom extends Record<"from", string | null> = { from: null },
+> {
+  private _fast: Fast;
+  private _from: TFrom;
+
+  constructor(fast = { fast: false } as Fast, from = { from: null } as TFrom) {
+    this._fast = fast;
+    this._from = from;
+  }
+
+  fast(): DateFieldBuilder<{ fast: true }, TFrom> {
+    return new DateFieldBuilder({ fast: true }, this._from);
+  }
+
+  from(field: string): DateFieldBuilder<Fast, { from: string }> {
+    return new DateFieldBuilder(this._fast, { from: field } as { from: string });
+  }
+
+  [BUILD](): Fast extends { fast: true }
+    ? TFrom["from"] extends string
+      ? { type: "DATE"; fast: true; from: TFrom["from"] }
+      : { type: "DATE"; fast: true }
+    : TFrom["from"] extends string
+      ? { type: "DATE"; from: TFrom["from"] }
+      : { type: "DATE" } {
+    const hasFast = this._fast.fast;
+    const hasFrom = Boolean(this._from.from);
+
+    if (hasFast && hasFrom) {
+      return {
+        type: "DATE",
+        fast: true,
+        from: this._from.from,
+      } as any;
+    }
+    if (hasFast) {
+      return {
+        type: "DATE",
+        fast: true,
+      } as any;
+    }
+    if (hasFrom) {
+      return {
+        type: "DATE",
+        from: this._from.from,
+      } as any;
+    }
+    return { type: "DATE" } as any;
+  }
+}
+
+class HybridFieldBuilder<
+  TNoStem extends Record<"noStem", boolean> = { noStem: false },
+  TFrom extends Record<"from", string | null> = { from: null },
+> {
+  private _noStem: TNoStem;
+  private _from: TFrom;
+
+  constructor(noStem = { noStem: false } as TNoStem, from = { from: null } as TFrom) {
+    this._noStem = noStem;
+    this._from = from;
+  }
+
+  noStem(): HybridFieldBuilder<{ noStem: true }, TFrom> {
+    return new HybridFieldBuilder({ noStem: true }, this._from);
+  }
+
+  from(field: string): HybridFieldBuilder<TNoStem, { from: string }> {
+    return new HybridFieldBuilder(this._noStem, { from: field } as { from: string });
+  }
+
+  [BUILD](): { type: "HYBRID" } & (TNoStem["noStem"] extends true
+    ? { noStem: true }
+    : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+      {}) &
+    (TFrom["from"] extends string
+      ? { from: TFrom["from"] }
+      : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        {}) {
+    return {
+      type: "HYBRID",
+      ...(this._noStem.noStem ? { noStem: true } : {}),
+      ...(this._from.from ? { from: this._from.from } : {}),
+    } as any;
+  }
+}
+
+class KeywordFieldBuilder {
+  [BUILD](): { type: "KEYWORD" } {
+    return { type: "KEYWORD" } as const;
+  }
+}
+
+class FacetFieldBuilder {
+  [BUILD](): { type: "FACET" } {
+    return { type: "FACET" } as const;
+  }
+}
+
+type FieldBuilder =
+  | TextFieldBuilder<{ noTokenize: boolean }, { noStem: boolean }, { from: string | null }>
+  | NumericFieldBuilder<NumericField["type"], { from: string | null }>
+  | BoolFieldBuilder<{ fast: boolean }, { from: string | null }>
+  | DateFieldBuilder<{ fast: boolean }, { from: string | null }>
+  | HybridFieldBuilder<{ noStem: boolean }, { from: string | null }>
+  | KeywordFieldBuilder
+  | FacetFieldBuilder;
+
+export const s = {
+  string(): TextFieldBuilder {
+    return new TextFieldBuilder();
+  },
+  number<T extends NumericField["type"] = "F64">(type: T = "F64" as T): NumericFieldBuilder<T> {
+    return new NumericFieldBuilder(type);
+  },
+  boolean(): BoolFieldBuilder {
+    return new BoolFieldBuilder();
+  },
+  date(): DateFieldBuilder {
+    return new DateFieldBuilder();
+  },
+  /**
+   * A TEXT field that is also embedded for semantic search with `$ann`.
+   *
+   * @see https://upstash.com/docs/redis/search/hybrid-search
+   */
+  hybrid(): HybridFieldBuilder {
+    return new HybridFieldBuilder();
+  },
+  keyword(): KeywordFieldBuilder {
+    return new KeywordFieldBuilder();
+  },
+  facet(): FacetFieldBuilder {
+    return new FacetFieldBuilder();
+  },
+  object<T extends ObjectFieldRecord<T>>(fields: T) {
+    const result: any = {};
+    for (const [key, value] of Object.entries(fields)) {
+      // eslint-disable-next-line unicorn/prefer-ternary
+      if (value && typeof value === "object" && BUILD in value) {
+        // It's a field builder
+        result[key] = (value as any)[BUILD]();
+      } else {
+        // It's a nested object/schema
+        result[key] = value;
+      }
+    }
+    return result as {
+      [K in keyof T]: T[K] extends FieldBuilder ? ReturnType<T[K][typeof BUILD]> : T[K];
+    };
+  },
+};
+
+type ObjectFieldRecord<T> = {
+  [K in keyof T]: K extends string
+    ? K extends `${infer _}.${infer _}`
+      ? never
+      : T[K] extends FieldBuilder | NestedIndexSchema
+        ? T[K]
+        : never
+    : never;
+};

package/src/pkg/commands/search/search.ts

@@ -0,0 +1,218 @@
+import type {
+  AggregateOptions,
+  AggregateResult,
+  CountRetriever,
+  FlatIndexSchema,
+  IndexDescription,
+  Language,
+  NestedIndexSchema,
+  QueryOptions,
+  QueryResult,
+  RootQueryFilter,
+} from "./types";
+import type { Requester } from "../../http";
+import { ExecCommand } from "../exec";
+import {
+  buildAggregateCommand,
+  buildCreateIndexCommand,
+  buildQueryCommand,
+} from "./command-builder";
+import {
+  deserializeAggregateResponse,
+  deserializeDescribeResponse,
+  deserializeQueryResponse,
+  parseCountResponse,
+} from "./utils";
+
+export type CreateIndexParameters<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  name: string;
+  language?: Language;
+  skipInitialScan?: boolean;
+  existsOk?: boolean;
+} & (
+  | {
+      dataType: "string";
+      prefix: string | string[];
+      schema: TSchema extends NestedIndexSchema ? TSchema : never;
+    }
+  | {
+      dataType: "json";
+      prefix: string | string[];
+      schema: TSchema extends NestedIndexSchema ? TSchema : never;
+    }
+  | {
+      dataType: "hash";
+      prefix: string | string[];
+      schema: TSchema extends FlatIndexSchema ? TSchema : never;
+    }
+  | {
+      /**
+       * Index the entries of a single Redis stream. Each entry becomes a document whose key is
+       * the entry ID and whose fields are the entry's fields.
+       *
+       * @see https://upstash.com/docs/redis/search/streams
+       */
+      dataType: "stream";
+      /**
+       * Exact key of the stream to index. The stream does not need to exist yet.
+       */
+      stream: string;
+      prefix?: never;
+      schema: TSchema extends FlatIndexSchema ? TSchema : never;
+    }
+);
+
+export type InitIndexParameters<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  name: string;
+  schema?: TSchema;
+};
+
+export type SearchIndexParameters<TSchema extends NestedIndexSchema | FlatIndexSchema> = {
+  name: string;
+  client: Requester;
+  schema?: TSchema;
+};
+
+export class SearchIndex<TSchema extends NestedIndexSchema | FlatIndexSchema> {
+  readonly name: SearchIndexParameters<TSchema>["name"];
+  readonly schema?: TSchema;
+  private client: Requester;
+
+  constructor({ name, schema, client }: SearchIndexParameters<TSchema>) {
+    this.name = name;
+    this.schema = schema;
+    this.client = client;
+  }
+
+  async waitIndexing(): Promise<0 | 1> {
+    const command = ["SEARCH.WAITINDEXING", this.name];
+    return await new ExecCommand<0 | 1>(command as [string, ...string[]]).exec(this.client);
+  }
+
+  async describe(): Promise<IndexDescription<TSchema> | null> {
+    const command = ["SEARCH.DESCRIBE", this.name];
+    const rawResult = await new ExecCommand<any>(command as [string, ...string[]]).exec(
+      this.client
+    );
+    if (!rawResult) return null;
+    return deserializeDescribeResponse<TSchema>(rawResult);
+  }
+
+  async query<TOpts extends QueryOptions<TSchema>>(
+    options?: TOpts
+  ): Promise<QueryResult<TSchema, TOpts>[]> {
+    const command = buildQueryCommand<TSchema>("SEARCH.QUERY", this.name, options);
+    const rawResult = await new ExecCommand<string[]>(command as [string, ...string[]]).exec(
+      this.client
+    );
+    if (!rawResult) return rawResult;
+    return deserializeQueryResponse<TSchema, TOpts>(rawResult);
+  }
+
+  async aggregate<TOpts extends AggregateOptions<TSchema>>(
+    options: TOpts
+  ): Promise<AggregateResult<TSchema, TOpts>> {
+    const command = buildAggregateCommand(this.name, options);
+    const rawResult = await new ExecCommand<(string | number)[]>(
+      command as [string, ...string[]]
+    ).exec(this.client);
+    return deserializeAggregateResponse(rawResult);
+  }
+
+  async count({
+    filter,
+  }: {
+    filter: RootQueryFilter<TSchema> | CountRetriever<TSchema>;
+  }): Promise<{ count: number }> {
+    const command = buildQueryCommand<TSchema>("SEARCH.COUNT", this.name, {
+      filter,
+    } as QueryOptions<TSchema>);
+    const rawResult = await new ExecCommand<any>(command as [string, ...string[]]).exec(
+      this.client
+    );
+    return { count: parseCountResponse(rawResult) };
+  }
+
+  async drop(): Promise<1 | 0> {
+    const command = ["SEARCH.DROP", this.name];
+    const result = await new ExecCommand<1 | 0>(command as [string, ...string[]]).exec(this.client);
+    return result;
+  }
+
+  async addAlias({ alias }: { alias: string }): Promise<1> {
+    const command = ["SEARCH.ALIASADD", alias, this.name];
+    const result = await new ExecCommand<1>(command as [string, ...string[]]).exec(this.client);
+    return result;
+  }
+}
+
+export async function createIndex<TSchema extends NestedIndexSchema | FlatIndexSchema>(
+  client: Requester,
+  params: CreateIndexParameters<TSchema>
+): Promise<SearchIndex<TSchema>> {
+  const { name, schema } = params;
+  const createIndexCommand = buildCreateIndexCommand<TSchema>(params);
+  await new ExecCommand<string>(createIndexCommand as [string, ...string[]]).exec(client);
+
+  return initIndex(client, { name, schema: schema as TSchema });
+}
+
+export function initIndex(
+  client: Requester,
+  params: Pick<InitIndexParameters<any>, "name">
+): SearchIndex<any>;
+export function initIndex<TSchema extends NestedIndexSchema | FlatIndexSchema>(
+  client: Requester,
+  params: InitIndexParameters<TSchema>
+): SearchIndex<TSchema>;
+export function initIndex<TSchema extends NestedIndexSchema | FlatIndexSchema>(
+  client: Requester,
+  params: InitIndexParameters<TSchema>
+): SearchIndex<TSchema> {
+  const { name, schema } = params;
+  return new SearchIndex<TSchema>({ name, schema, client });
+}
+
+export type InferFilterFromSchema<TSchema extends NestedIndexSchema | FlatIndexSchema> =
+  NonNullable<NonNullable<Parameters<SearchIndex<TSchema>["query"]>[0]>["filter"]>;
+
+export async function listAliases(client: Requester): Promise<Record<string, string>> {
+  const command = ["SEARCH.LISTALIASES"];
+  const rawResult = await new ExecCommand<any>(command as [string, ...string[]]).exec(client);
+
+  // Handle empty case - might be 0 or an empty array
+  if (rawResult === 0 || (Array.isArray(rawResult) && rawResult.length === 0)) {
+    return {};
+  }
+
+  // Parse the response: [[alias1, index1], [alias2, index2], ...]
+  if (!Array.isArray(rawResult)) {
+    return {};
+  }
+
+  const aliases: Record<string, string> = {};
+
+  for (const pair of rawResult) {
+    if (Array.isArray(pair) && pair.length === 2) {
+      const [alias, index] = pair;
+      aliases[alias] = index;
+    }
+  }
+
+  return aliases;
+}
+
+export async function addAlias(
+  client: Requester,
+  { indexName, alias }: { indexName: string; alias: string }
+): Promise<1 | 2> {
+  const command = ["SEARCH.ALIASADD", alias, indexName];
+  const result = await new ExecCommand<1 | 2>(command as [string, ...string[]]).exec(client);
+  return result;
+}
+
+export async function delAlias(client: Requester, { alias }: { alias: string }): Promise<0 | 1> {
+  const command = ["SEARCH.ALIASDEL", alias];
+  const result = await new ExecCommand<0 | 1>(command as [string, ...string[]]).exec(client);
+  return result;
+}