redis-vl 0.1.0-beta.0

package/dist/schema/schema.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+import { StorageType } from './types.js';
+import { BaseField, TextFieldAttrs, TagFieldAttrs, NumericFieldAttrs, GeoFieldAttrs, VectorFieldAttrs } from './fields.js';
+/**
+ * Zod schema for IndexInfo validation.
+ * Validates index configuration including name, prefix, key separator, storage type, and stopwords.
+ */
+export declare const IndexInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    prefix: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    keySeparator: z.ZodDefault<z.ZodString>;
+    storageType: z.ZodDefault<z.ZodEnum<typeof StorageType>>;
+    stopwords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * TypeScript type inferred from IndexInfoSchema.
+ */
+export type IndexInfoOptions = z.input<typeof IndexInfoSchema>;
+/**
+ * IndexInfo includes the essential details regarding index settings,
+ * such as its name, prefix, key separator, storage type, and stopwords in Redis.
+ */
+export declare class IndexInfo {
+    /** The unique name of the index */
+    readonly name: string;
+    /** The prefix(es) used for Redis keys associated with this index */
+    readonly prefix: string | string[];
+    /** The separator character used in designing Redis keys */
+    readonly keySeparator: string;
+    /** The storage type used in Redis (e.g., StorageType.HASH or StorageType.JSON) */
+    readonly storageType: StorageType;
+    /** Index-level stopwords configuration */
+    readonly stopwords?: string[];
+    constructor(options: IndexInfoOptions);
+}
+/**
+ * Zod schema for IndexSchema validation.
+ */
+export declare const IndexSchemaOptionsSchema: z.ZodObject<{
+    index: z.ZodCustom<IndexInfo, IndexInfo>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<BaseField, BaseField>>>;
+    version: z.ZodOptional<z.ZodLiteral<"0.1.0">>;
+}, z.core.$strip>;
+/**
+ * TypeScript type inferred from IndexSchemaOptionsSchema.
+ */
+export type IndexSchemaOptions = z.input<typeof IndexSchemaOptionsSchema>;
+/**
+ * Field input type for addField and addFields methods.
+ *
+ * The attrs property is type-safe based on the field type:
+ * - text: TextFieldAttrs
+ * - tag: TagFieldAttrs
+ * - numeric: NumericFieldAttrs
+ * - geo: GeoFieldAttrs
+ * - vector: VectorFieldAttrs (FLAT or HNSW)
+ */
+export type FieldInput = {
+    name: string;
+    type: 'text';
+    attrs?: TextFieldAttrs;
+    path?: string;
+} | {
+    name: string;
+    type: 'tag';
+    attrs?: TagFieldAttrs;
+    path?: string;
+} | {
+    name: string;
+    type: 'numeric';
+    attrs?: NumericFieldAttrs;
+    path?: string;
+} | {
+    name: string;
+    type: 'geo';
+    attrs?: GeoFieldAttrs;
+    path?: string;
+} | {
+    name: string;
+    type: 'vector';
+    attrs?: VectorFieldAttrs;
+    path?: string;
+} | {
+    name: string;
+    type: string;
+    attrs?: Record<string, unknown>;
+    path?: string;
+};
+/**
+ * A schema definition for a search index in Redis, used in RedisVL for
+ * configuring index settings and organizing vector and metadata fields.
+ */
+export declare class IndexSchema {
+    /** Details of the basic index configurations */
+    readonly index: IndexInfo;
+    /** Fields associated with the search index and their properties */
+    fields: Record<string, BaseField>;
+    /** Version of the underlying index schema */
+    readonly version: '0.1.0';
+    constructor(options: IndexSchemaOptions);
+    /**
+     * A list of field names associated with the index schema.
+     *
+     * @returns A list of field names from the schema
+     */
+    get fieldNames(): string[];
+    /**
+     * Internal helper to create a field and set its path based on storage type.
+     * For JSON storage: auto-sets path to $.fieldname if not provided.
+     * For HASH storage: sets path to null (paths not used).
+     */
+    private makeField;
+    /**
+     * Adds a single field to the index schema.
+     *
+     * @param fieldInputs - Field definition object with name, type, and optional attributes
+     * @throws {Error} If a field with the same name already exists
+     *
+     * @example
+     * ```typescript
+     * schema.addField({ name: 'title', type: 'text' });
+     * schema.addField({
+     *   name: 'embedding',
+     *   type: 'vector',
+     *   attrs: { dims: 1536, algorithm: 'hnsw' }
+     * });
+     * ```
+     */
+    addField(fieldInputs: FieldInput): void;
+    /**
+     * Adds multiple fields to the index schema.
+     *
+     * @param fields - Array of field definition objects
+     * @throws {Error} If any field has a duplicate name
+     *
+     * @example
+     * ```typescript
+     * schema.addFields([
+     *   { name: 'title', type: 'text' },
+     *   { name: 'category', type: 'tag' },
+     *   { name: 'price', type: 'numeric' }
+     * ]);
+     * ```
+     */
+    addFields(fields: FieldInput[]): void;
+    /**
+     * Removes a field from the schema by name.
+     *
+     * @param fieldName - The name of the field to remove
+     *
+     * @example
+     * ```typescript
+     * schema.removeField('old_field');
+     * ```
+     */
+    removeField(fieldName: string): void;
+    /**
+     * Create an IndexSchema from a plain object.
+     * Accepts both snake_case (from YAML/JSON files) and camelCase (from TypeScript) property names.
+     *
+     * @param data - The index schema data
+     * @returns A new IndexSchema instance
+     *
+     * @example
+     * ```typescript
+     * // From YAML/JSON (snake_case)
+     * const schema = IndexSchema.fromObject({
+     *   index: {
+     *     name: 'docs-index',
+     *     prefix: 'docs',
+     *     storage_type: 'hash',  // snake_case from YAML/JSON
+     *   },
+     *   fields: [
+     *     { name: 'doc-id', type: 'tag' },
+     *     { name: 'title', type: 'text' }
+     *   ]
+     * });
+     * ```
+     */
+    static fromObject(data: {
+        index: IndexInfoOptions | IndexInfo | Record<string, unknown>;
+        fields?: FieldInput[] | Record<string, FieldInput>;
+        version?: '0.1.0';
+    }): IndexSchema;
+    /**
+     * Create an IndexSchema from a YAML file.
+     *
+     * @param filePath - The path to the YAML file
+     * @returns A new IndexSchema instance
+     *
+     * @throws Error if the file path is invalid
+     * @throws Error if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const schema = await IndexSchema.fromYAML('schema.yaml');
+     * console.log(schema.index.name);
+     * ```
+     */
+    static fromYAML(filePath: string): Promise<IndexSchema>;
+    /**
+     * Serialize the index schema to a plain object.
+     * Converts camelCase properties to snake_case for YAML/JSON compatibility.
+     *
+     * @returns The index schema as a plain object with snake_case keys
+     *
+     * @example
+     * ```typescript
+     * const schema = new IndexSchema({ index: indexInfo });
+     * const obj = schema.toObject();
+     * console.log(obj.index.name);
+     * console.log(obj.index.storage_type);
+     * ```
+     */
+    toObject(): {
+        index: {
+            name: string;
+            prefix: string | string[];
+            key_separator: string;
+            storage_type: string;
+            stopwords?: string[];
+        };
+        fields: Array<{
+            name: string;
+            type: string;
+            attrs?: Record<string, unknown>;
+            path?: string;
+        }>;
+        version: '0.1.0';
+    };
+    /**
+     * Write the index schema to a YAML file.
+     *
+     * @param filePath - The path to the YAML file
+     * @param overwrite - Whether to overwrite the file if it already exists (default: true)
+     *
+     * @throws Error if the file already exists and overwrite is false
+     *
+     * @example
+     * ```typescript
+     * const schema = new IndexSchema({ index: indexInfo });
+     * await schema.toYAML('schema.yaml');
+     * ```
+     */
+    toYAML(filePath: string, overwrite?: boolean): Promise<void>;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema/schema.js

@@ -0,0 +1,403 @@
+import { z } from 'zod';
+import * as yaml from 'js-yaml';
+import { promises as fs } from 'fs';
+import { resolve } from 'path';
+import { StorageType } from './types.js';
+import { BaseField, FieldFactory, } from './fields.js';
+import { SchemaValidationError, RedisVLError } from '../errors.js';
+/**
+ * Zod schema for IndexInfo validation.
+ * Validates index configuration including name, prefix, key separator, storage type, and stopwords.
+ */
+export const IndexInfoSchema = z.object({
+    name: z
+        .string()
+        .min(1, 'IndexInfo name cannot be empty')
+        .meta({
+        title: 'Index Name',
+        description: 'The unique name of the index (required, non-empty)',
+        examples: ['user-index', 'product-search', 'document-embeddings'],
+    }),
+    prefix: z
+        .union([z.string(), z.array(z.string())])
+        .default('rvl')
+        .meta({
+        title: 'Key Prefix',
+        description: 'The prefix(es) used for Redis keys associated with this index. ' +
+            'Can be a single string or array of strings. ' +
+            'When multiple prefixes are provided, the first one is used for write operations, but the index searches across all prefixes.',
+        examples: ['user', ['user', 'person', 'customer'], 'product'],
+    }),
+    keySeparator: z
+        .string()
+        .default(':')
+        .meta({
+        title: 'Key Separator',
+        description: 'The separator character used between prefix and key in Redis keys',
+        examples: [':', '::', '-', '_'],
+    }),
+    storageType: z
+        .enum(StorageType)
+        .default(StorageType.HASH)
+        .meta({
+        title: 'Storage Type',
+        description: 'The storage type used in Redis. ' +
+            'Options: "hash" (HASH storage) or "json" (JSON storage)',
+        examples: ['hash', 'json'],
+    }),
+    stopwords: z
+        .array(z.string())
+        .optional()
+        .meta({
+        title: 'Stopwords',
+        description: 'Index-level stopwords configuration for full-text search. ' +
+            'undefined (default) uses Redis default stopwords, ' +
+            'empty array [] disables stopwords (STOPWORDS 0), ' +
+            'or provide a custom list',
+        examples: [[], ['the', 'a', 'an', 'and', 'or']],
+    }),
+});
+/**
+ * IndexInfo includes the essential details regarding index settings,
+ * such as its name, prefix, key separator, storage type, and stopwords in Redis.
+ */
+export class IndexInfo {
+    /** The unique name of the index */
+    name;
+    /** The prefix(es) used for Redis keys associated with this index */
+    prefix;
+    /** The separator character used in designing Redis keys */
+    keySeparator;
+    /** The storage type used in Redis (e.g., StorageType.HASH or StorageType.JSON) */
+    storageType;
+    /** Index-level stopwords configuration */
+    stopwords;
+    constructor(options) {
+        // Validate and parse options using Zod
+        const validated = IndexInfoSchema.parse(options);
+        this.name = validated.name;
+        this.prefix = validated.prefix;
+        this.keySeparator = validated.keySeparator;
+        this.storageType = validated.storageType;
+        this.stopwords = validated.stopwords;
+    }
+}
+/**
+ * Zod schema for IndexSchema validation.
+ */
+export const IndexSchemaOptionsSchema = z.object({
+    /** Details of the basic index configurations */
+    index: z.instanceof(IndexInfo),
+    /** Fields associated with the search index and their properties */
+    fields: z.record(z.string(), z.instanceof(BaseField)).optional(),
+    /** Version of the underlying index schema */
+    version: z.literal('0.1.0').optional(),
+});
+/**
+ * A schema definition for a search index in Redis, used in RedisVL for
+ * configuring index settings and organizing vector and metadata fields.
+ */
+export class IndexSchema {
+    /** Details of the basic index configurations */
+    index;
+    /** Fields associated with the search index and their properties */
+    fields;
+    /** Version of the underlying index schema */
+    version;
+    constructor(options) {
+        // Validate options using Zod
+        const validated = IndexSchemaOptionsSchema.parse(options);
+        this.index = validated.index;
+        this.fields = validated.fields ?? {};
+        this.version = validated.version ?? '0.1.0';
+    }
+    /**
+     * A list of field names associated with the index schema.
+     *
+     * @returns A list of field names from the schema
+     */
+    get fieldNames() {
+        return Object.keys(this.fields);
+    }
+    /**
+     * Internal helper to create a field and set its path based on storage type.
+     * For JSON storage: auto-sets path to $.fieldname if not provided.
+     * For HASH storage: sets path to null (paths not used).
+     */
+    makeField(storageType, fieldInputs) {
+        // Extract field properties from inputs
+        const { name, type, attrs, path } = fieldInputs;
+        if (!name) {
+            throw new SchemaValidationError('Field name is required');
+        }
+        if (!type) {
+            throw new SchemaValidationError('Field type is required');
+        }
+        // Create field from inputs using FieldFactory
+        const field = FieldFactory.createField(type, name, attrs);
+        // Handle field path based on storage type
+        if (storageType === StorageType.JSON) {
+            // For JSON storage, set path appropriately
+            if (path) {
+                // Explicit path provided, use it
+                field.path = path;
+            }
+            else if (field.name.startsWith('$.')) {
+                // Name already is a JSON path, use it as-is
+                field.path = field.name;
+            }
+            else {
+                // Name is a simple field name, add $.prefix
+                field.path = `$.${field.name}`;
+            }
+        }
+        else {
+            // For HASH storage, path should always be null
+            if (path !== null && path !== undefined) {
+                // TODO: log a warning
+            }
+            field.path = null;
+        }
+        return field;
+    }
+    /**
+     * Adds a single field to the index schema.
+     *
+     * @param fieldInputs - Field definition object with name, type, and optional attributes
+     * @throws {Error} If a field with the same name already exists
+     *
+     * @example
+     * ```typescript
+     * schema.addField({ name: 'title', type: 'text' });
+     * schema.addField({
+     *   name: 'embedding',
+     *   type: 'vector',
+     *   attrs: { dims: 1536, algorithm: 'hnsw' }
+     * });
+     * ```
+     */
+    addField(fieldInputs) {
+        // Create field with proper path handling
+        const field = this.makeField(this.index.storageType, fieldInputs);
+        // Check for duplicates
+        if (Object.hasOwn(this.fields, field.name)) {
+            throw new SchemaValidationError(`Duplicate field name: ${field.name}. Field names must be unique across all fields for this index.`);
+        }
+        // Add field to schema
+        this.fields[field.name] = field;
+    }
+    /**
+     * Adds multiple fields to the index schema.
+     *
+     * @param fields - Array of field definition objects
+     * @throws {Error} If any field has a duplicate name
+     *
+     * @example
+     * ```typescript
+     * schema.addFields([
+     *   { name: 'title', type: 'text' },
+     *   { name: 'category', type: 'tag' },
+     *   { name: 'price', type: 'numeric' }
+     * ]);
+     * ```
+     */
+    addFields(fields) {
+        for (const fieldInput of fields) {
+            this.addField(fieldInput);
+        }
+    }
+    /**
+     * Removes a field from the schema by name.
+     *
+     * @param fieldName - The name of the field to remove
+     *
+     * @example
+     * ```typescript
+     * schema.removeField('old_field');
+     * ```
+     */
+    removeField(fieldName) {
+        if (!Object.hasOwn(this.fields, fieldName)) {
+            // TODO: log a warning
+            return;
+        }
+        delete this.fields[fieldName];
+    }
+    /**
+     * Create an IndexSchema from a plain object.
+     * Accepts both snake_case (from YAML/JSON files) and camelCase (from TypeScript) property names.
+     *
+     * @param data - The index schema data
+     * @returns A new IndexSchema instance
+     *
+     * @example
+     * ```typescript
+     * // From YAML/JSON (snake_case)
+     * const schema = IndexSchema.fromObject({
+     *   index: {
+     *     name: 'docs-index',
+     *     prefix: 'docs',
+     *     storage_type: 'hash',  // snake_case from YAML/JSON
+     *   },
+     *   fields: [
+     *     { name: 'doc-id', type: 'tag' },
+     *     { name: 'title', type: 'text' }
+     *   ]
+     * });
+     * ```
+     */
+    static fromObject(data) {
+        // 1. Create IndexInfo if it's a plain object
+        let indexInfo;
+        if (data.index instanceof IndexInfo) {
+            indexInfo = data.index;
+        }
+        else {
+            // Convert snake_case to camelCase for IndexInfo properties
+            const indexData = { ...data.index };
+            // Handle storage_type -> storageType conversion
+            if ('storage_type' in indexData && !('storageType' in indexData)) {
+                indexData.storageType = indexData.storage_type;
+                delete indexData.storage_type;
+            }
+            // Handle key_separator -> keySeparator conversion
+            if ('key_separator' in indexData && !('keySeparator' in indexData)) {
+                indexData.keySeparator = indexData.key_separator;
+                delete indexData.key_separator;
+            }
+            indexInfo = new IndexInfo(indexData);
+        }
+        // 2. Create empty schema
+        const schema = new IndexSchema({
+            index: indexInfo,
+            version: data.version,
+        });
+        // 3. Add fields if provided
+        if (data.fields) {
+            if (Array.isArray(data.fields)) {
+                // Handle array format
+                schema.addFields(data.fields);
+            }
+            else {
+                // Handle object format
+                for (const [key, fieldData] of Object.entries(data.fields)) {
+                    // Validate field name matches key
+                    if (fieldData.name !== key) {
+                        throw new SchemaValidationError(`Field name mismatch: key is "${key}" but field.name is "${fieldData.name}"`);
+                    }
+                    schema.addField(fieldData);
+                }
+            }
+        }
+        return schema;
+    }
+    /**
+     * Create an IndexSchema from a YAML file.
+     *
+     * @param filePath - The path to the YAML file
+     * @returns A new IndexSchema instance
+     *
+     * @throws Error if the file path is invalid
+     * @throws Error if the file does not exist
+     *
+     * @example
+     * ```typescript
+     * const schema = await IndexSchema.fromYAML('schema.yaml');
+     * console.log(schema.index.name);
+     * ```
+     */
+    static async fromYAML(filePath) {
+        const resolvedPath = resolve(filePath);
+        // Check if file exists
+        try {
+            await fs.access(resolvedPath);
+        }
+        catch {
+            throw new RedisVLError(`Schema file ${filePath} does not exist`);
+        }
+        // Read and parse YAML file
+        const yamlContent = await fs.readFile(resolvedPath, 'utf-8');
+        const data = yaml.load(yamlContent);
+        // Use fromObject to create the schema
+        return IndexSchema.fromObject(data);
+    }
+    /**
+     * Serialize the index schema to a plain object.
+     * Converts camelCase properties to snake_case for YAML/JSON compatibility.
+     *
+     * @returns The index schema as a plain object with snake_case keys
+     *
+     * @example
+     * ```typescript
+     * const schema = new IndexSchema({ index: indexInfo });
+     * const obj = schema.toObject();
+     * console.log(obj.index.name);
+     * console.log(obj.index.storage_type);
+     * ```
+     */
+    toObject() {
+        // Serialize index info - convert camelCase to snake_case
+        const indexDict = {
+            name: this.index.name,
+            prefix: this.index.prefix,
+            key_separator: this.index.keySeparator, // camelCase -> snake_case
+            storage_type: this.index.storageType, // camelCase -> snake_case (enum value is already string)
+            ...(this.index.stopwords !== undefined && { stopwords: this.index.stopwords }),
+        };
+        // Serialize fields as array
+        const fieldsArray = Object.values(this.fields).map((field) => {
+            const fieldDict = {
+                name: field.name,
+                type: field.type,
+            };
+            if (Object.keys(field.attrs).length > 0) {
+                fieldDict.attrs = field.attrs;
+            }
+            if (field.path !== undefined && field.path !== null) {
+                fieldDict.path = field.path;
+            }
+            return fieldDict;
+        });
+        return {
+            index: indexDict,
+            fields: fieldsArray,
+            version: this.version,
+        };
+    }
+    /**
+     * Write the index schema to a YAML file.
+     *
+     * @param filePath - The path to the YAML file
+     * @param overwrite - Whether to overwrite the file if it already exists (default: true)
+     *
+     * @throws Error if the file already exists and overwrite is false
+     *
+     * @example
+     * ```typescript
+     * const schema = new IndexSchema({ index: indexInfo });
+     * await schema.toYAML('schema.yaml');
+     * ```
+     */
+    async toYAML(filePath, overwrite = true) {
+        const resolvedPath = resolve(filePath);
+        // Check if file exists
+        if (!overwrite) {
+            try {
+                await fs.access(resolvedPath);
+                throw new RedisVLError(`Schema file ${filePath} already exists.`);
+            }
+            catch (error) {
+                // File doesn't exist, which is what we want
+                if (error instanceof RedisVLError && error.message.includes('already exists')) {
+                    throw error;
+                }
+                // Otherwise, file doesn't exist, continue
+            }
+        }
+        // Convert to object and write as YAML
+        const objData = this.toObject();
+        const yamlData = yaml.dump(objData, { sortKeys: false });
+        await fs.writeFile(resolvedPath, yamlData, 'utf-8');
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema/schema.ts"],"names":[],"mappings":"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"}