@cleverbrush/schema 1.1.10 → 2.0.0

package/dist/builders/RecordSchemaBuilder.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Schema builder for objects with dynamic string keys, where every value
+ * must satisfy the same value schema.
+ *
+ * Equivalent to TypeScript's `Record<string, V>` (or a more constrained key
+ * set when using a string-literal key schema) and Zod's `z.record()`.
+ *
+ * Unlike `ObjectSchemaBuilder` — which validates objects with a **known,
+ * fixed set of property names** — `RecordSchemaBuilder` validates objects
+ * whose keys are not known at schema-definition time (look-up tables, i18n
+ * bundles, caches, etc.).
+ *
+ * @module
+ */
+import { type BRAND, type InferType, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+import type { StringSchemaBuilder } from './StringSchemaBuilder.js';
+/**
+ * Descriptor for a single key-value entry within a validated record.
+ * Provides `getValue`, `setValue`, and `getSchema` operations for the entry.
+ *
+ * Returned as part of {@link RecordKeyValidationResult}.
+ */
+export type RecordKeyDescriptor<TRecord, TValueSchema extends SchemaBuilder<any, any, any, any, any>> = {
+    /** The key within the record this descriptor refers to. */
+    readonly key: string;
+    /** Returns the value schema every record entry must satisfy. */
+    getSchema(): TValueSchema;
+    /**
+     * Retrieves the value at `key` from the given record object.
+     * Returns `{ success: false }` when the key is not present.
+     */
+    getValue(obj: TRecord): {
+        value?: InferType<TValueSchema>;
+        success: boolean;
+    };
+    /**
+     * Sets the value at `key` on the given record object.
+     * Returns `false` when `obj` is not a non-null object.
+     */
+    setValue(obj: TRecord, value: InferType<TValueSchema>): boolean;
+};
+/**
+ * Validation result for a single key-value entry in a record.
+ * Returned by {@link RecordSchemaValidationResult.getErrorsFor | getErrorsFor(key)}.
+ */
+export type RecordKeyValidationResult<TRecord, TValueSchema extends SchemaBuilder<any, any, any, any, any>> = {
+    /** Validation error messages for this entry; empty array when valid. */
+    readonly errors: ReadonlyArray<string>;
+    /** `true` when there are no validation errors for this entry. */
+    readonly isValid: boolean;
+    /** The value that was seen at this key during validation. */
+    readonly seenValue: InferType<TValueSchema> | undefined;
+    /** Descriptor for reading/writing the value at this key. */
+    readonly descriptor: RecordKeyDescriptor<TRecord, TValueSchema>;
+};
+/**
+ * Root-level validation result for the record object itself.
+ * Returned by {@link RecordSchemaValidationResult.getErrorsFor | getErrorsFor()} (no argument).
+ */
+export type RecordRootValidationResult<TResult> = {
+    /** Root-level error messages (e.g. `"object expected"`); empty when valid. */
+    readonly errors: ReadonlyArray<string>;
+    /** `true` when there are no root-level errors. */
+    readonly isValid: boolean;
+    /** The value that was being validated. */
+    readonly seenValue: TResult | undefined;
+};
+/**
+ * Validation result type returned by `RecordSchemaBuilder.validate()`.
+ *
+ * Extends `ValidationResult` with:
+ * - `getNestedErrors()` — a per-key map of `ValidationResult` objects.
+ * - `getErrorsFor()` — root-level errors for the record container itself.
+ * - `getErrorsFor(key)` — errors, seen value, and descriptor for a specific key.
+ */
+export type RecordSchemaValidationResult<TResult, TValueSchema extends SchemaBuilder<any, any, any, any, any>> = ValidationResult<TResult> & {
+    /**
+     * Returns per-key validation results as a plain object.
+     *
+     * Each key in the returned object corresponds to a key in the input that
+     * **failed** validation (in `doNotStopOnFirstError` mode) or the single
+     * first failing key (in the default stop-on-first-error mode). Keys that
+     * passed are not included.
+     *
+     * @deprecated Prefer {@link getErrorsFor} for a richer per-entry result
+     * that also includes a descriptor and `seenValue`.
+     *
+     * @example
+     * ```ts
+     * const schema = record(string(), number().positive());
+     * const result = schema.validate(
+     *   { a: 1, b: -2, c: 'oops' },
+     *   { doNotStopOnFirstError: true }
+     * );
+     *
+     * if (!result.valid) {
+     *   const nested = result.getNestedErrors();
+     *   console.log(nested['b']); // ValidationResult for key 'b'
+     *   console.log(nested['c']); // ValidationResult for key 'c'
+     * }
+     * ```
+     */
+    getNestedErrors(): Record<string, ValidationResult<InferType<TValueSchema>>>;
+    /**
+     * Returns root-level errors for the record container itself
+     * (e.g. `"object expected"` when a non-object value is passed,
+     * or errors from custom validators added to the record schema).
+     *
+     * @example
+     * ```ts
+     * const schema = record(string(), number());
+     * const root = schema.validate(42 as any).getErrorsFor();
+     * // root.errors[0] === 'object expected'
+     * // root.isValid === false
+     * ```
+     */
+    getErrorsFor(): RecordRootValidationResult<TResult>;
+    /**
+     * Returns the validation result for the entry with the given key,
+     * including error messages, the seen value, and a descriptor for
+     * accessing and modifying the value at that key.
+     *
+     * If the key was not reached during validation (e.g. an earlier key
+     * already failed in stop-on-first-error mode), an empty result with
+     * `isValid: true` and no errors is returned.
+     *
+     * @param key - the key whose validation result to retrieve
+     *
+     * @example
+     * ```ts
+     * const schema = record(string(), number().min(0));
+     * const result = schema.validate(
+     *   { a: 5, b: -2 },
+     *   { doNotStopOnFirstError: true }
+     * );
+     *
+     * const bErrors = result.getErrorsFor('b');
+     * // bErrors.isValid === false
+     * // bErrors.errors[0] === 'the value must be >= 0'
+     * // bErrors.seenValue === -2
+     * // bErrors.descriptor.key === 'b'
+     * // bErrors.descriptor.getSchema() === valueSchema
+     * ```
+     */
+    getErrorsFor(key: string): RecordKeyValidationResult<TResult, TValueSchema>;
+};
+type RecordSchemaBuilderCreateProps<TKeySchema extends StringSchemaBuilder<any, any, any, any>, TValueSchema extends SchemaBuilder<any, any, any, any, any>, R extends boolean = true> = Partial<ReturnType<RecordSchemaBuilder<TKeySchema, TValueSchema, R>['introspect']>>;
+/**
+ * Schema builder for objects with dynamic string keys.
+ *
+ * Every key in the validated object must be accepted by `keySchema` (a
+ * `StringSchemaBuilder`) and every value must satisfy `valueSchema`.
+ *
+ * The inferred TypeScript type mirrors `Record<K, V>` where `K` is the
+ * string type produced by `keySchema` and `V` is the type produced by
+ * `valueSchema`.
+ *
+ * **NOTE** — this class is exported to allow extension by inheritance. Use
+ * the {@link record | record()} factory function instead of instantiating it
+ * directly.
+ *
+ * @example
+ * ```ts
+ * import { record, string, number } from '@cleverbrush/schema';
+ *
+ * // Basic: string keys, number values
+ * const scores = record(string(), number().min(0));
+ * // InferType<typeof scores> → Record<string, number>
+ *
+ * scores.validate({ alice: 95, bob: 87 }); // valid
+ * scores.validate({ alice: 95, bob: -1 }); // invalid (negative)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Restrict keys to a specific set of literals with .equals()
+ * const locales = record(
+ *   string().matches(/^[a-z]{2}(-[A-Z]{2})?$/),
+ *   string().nonempty()
+ * );
+ * // accepts: { en: 'Hello', fr: 'Bonjour' }
+ * // rejects: { 123: 'oops' }  ← key doesn't match pattern
+ * ```
+ *
+ * @see {@link record}
+ */
+export declare class RecordSchemaBuilder<TKeySchema extends StringSchemaBuilder<any, any, any, any>, TValueSchema extends SchemaBuilder<any, any, any, any, any>, TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResult = TExplicitType extends undefined ? Record<InferType<TKeySchema>, InferType<TValueSchema>> : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: RecordSchemaBuilderCreateProps<any, any, any>): RecordSchemaBuilder<StringSchemaBuilder<any, any, any, any, {}>, SchemaBuilder<any, any, any, any, any>, true, false, undefined, false, {}, Record<any, any>>;
+    protected constructor(props: RecordSchemaBuilderCreateProps<TKeySchema, TValueSchema, TRequired>);
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): RecordSchemaBuilder<TKeySchema, TValueSchema, true, TNullable, T, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    clearHasType(): RecordSchemaBuilder<TKeySchema, TValueSchema, TRequired, TNullable, undefined, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    protected createFromProps<TReq extends boolean>(props: RecordSchemaBuilderCreateProps<TKeySchema, TValueSchema, TReq>): this;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): RecordSchemaBuilder<TKeySchema, TValueSchema, true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): RecordSchemaBuilder<TKeySchema, TValueSchema, false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): RecordSchemaBuilder<TKeySchema, TValueSchema, true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): RecordSchemaBuilder<TKeySchema, TValueSchema, TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): RecordSchemaBuilder<TKeySchema, TValueSchema, TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Returns an introspection object describing the record schema.
+     */
+    introspect(): {
+        /**
+         * The schema every key must satisfy (a `StringSchemaBuilder`).
+         */
+        keySchema: TKeySchema;
+        /**
+         * The schema every value must satisfy.
+         */
+        valueSchema: TValueSchema;
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<TResult>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+    };
+    /**
+     * Core sync validation. {@inheritDoc SchemaBuilder.validate}
+     */
+    validate(object: TResult, context?: ValidationContext): RecordSchemaValidationResult<TResult, TValueSchema>;
+    /**
+     * Core async validation. {@inheritDoc SchemaBuilder.validateAsync}
+     */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<RecordSchemaValidationResult<TResult, TValueSchema>>;
+    /**
+     * Core sync validation. Returns `{ valid, object, errors, getNestedErrors, getErrorsFor }`.
+     */
+    protected _validate(object: TResult, context?: ValidationContext): RecordSchemaValidationResult<TResult, TValueSchema>;
+    /**
+     * Performs async validation of the record schema.
+     *
+     * Supports async preprocessors, validators, and error message providers.
+     *
+     * @param object - the value to validate
+     * @param context - optional `ValidationContext` settings
+     */
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<RecordSchemaValidationResult<TResult, TValueSchema>>;
+    /**
+     * @hidden
+     */
+    nullable(): RecordSchemaBuilder<TKeySchema, TValueSchema, TRequired, true, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): RecordSchemaBuilder<TKeySchema, TValueSchema, TRequired, false, TExplicitType, THasDefault, TExtensions> & TExtensions;
+}
+/**
+ * Creates a schema for objects with dynamic string keys, where every key
+ * must satisfy `keySchema` and every value must satisfy `valueSchema`.
+ *
+ * The inferred TypeScript type is `Record<K, V>` where `K` is derived from
+ * `keySchema` and `V` from `valueSchema`.
+ *
+ * @param keySchema  - a `StringSchemaBuilder` that each key must satisfy
+ * @param valueSchema - a `SchemaBuilder` that each value must satisfy
+ *
+ * @example
+ * ```ts
+ * import { record, string, number } from '@cleverbrush/schema';
+ *
+ * // Look-up table: string keys → number scores
+ * const scores = record(string(), number().min(0).max(100));
+ * // InferType<typeof scores> → Record<string, number>
+ *
+ * scores.validate({ alice: 95, bob: 87 }); // { valid: true }
+ * scores.validate({ alice: 95, bob: -1 }); // { valid: false }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // i18n bundle: locale code keys → non-empty strings
+ * const bundle = record(
+ *   string().matches(/^[a-z]{2}(-[A-Z]{2})?$/),
+ *   string().nonempty()
+ * );
+ *
+ * bundle.validate({ en: 'Hello', 'fr-FR': 'Bonjour' }); // valid
+ * bundle.validate({ en: '' });                            // invalid (empty value)
+ * bundle.validate({ '123': 'hi' });                      // invalid (bad key)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional record with a factory default
+ * const cache = record(string(), number())
+ *   .optional()
+ *   .default(() => ({}));
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Nested record — values are objects
+ * import { record, string, object, number } from '@cleverbrush/schema';
+ *
+ * const userMap = record(
+ *   string(),
+ *   object({ name: string(), age: number() })
+ * );
+ * ```
+ */
+export declare function record<TKeySchema extends StringSchemaBuilder<any, any, any, any>, TValueSchema extends SchemaBuilder<any, any, any, any, any>>(keySchema: TKeySchema, valueSchema: TValueSchema): RecordSchemaBuilder<TKeySchema, TValueSchema>;
+export {};

package/dist/builders/RecordSchemaBuilder.js

@@ -0,0 +1,2 @@
+import{a,b}from"../chunk-IJ6FO37G.js";import"../chunk-CTP4RHDG.js";export{a as RecordSchemaBuilder,b as record};
+//# sourceMappingURL=RecordSchemaBuilder.js.map

package/dist/builders/RecordSchemaBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}