@asaidimu/anansi 1.6.0 → 1.6.2

package/index.d.cts

@@ -175,6 +175,16 @@ type FieldType = "string" | "number" | "boolean" | "array" | "set" | "enum" | "o
 type IndexType = "normal" | "unique" | "btree" | "hash" | "spatial" | "fulltext" | "gi" | "expression" | "composite";
 /**
  * Defines a predicate function for data validation, mapped to a PredicateMap at runtime.
+ *
+ * @example
+ * ```typescript
+ * const isEmail: Predicate = ({ data, field, arguments: regex }) => {
+ *    if (field && typeof data[field] === 'string') {
+ *        return regex.test(data[field]);
+ *    }
+ *    return false;
+ * };
+ * ```
  */
 type Predicate = <T, K extends FieldType = any>(params: {
     data: T;
@@ -183,20 +193,53 @@ type Predicate = <T, K extends FieldType = any>(params: {
 }) => boolean;
 /**
  * A map of predicate names to their validation functions, implemented by the runtime environment.
+ *
+ * @example
+ * ```typescript
+ * const predicateMap: PredicateMap = {
+ *    isEmail: isEmail,
+ *    isPositive: ({ data, field, arguments: min }) => {
+ *        if (field && typeof data[field] === 'number'){
+ *            return data[field] > min;
+ *        }
+ *        return false;
+ *    }
+ * };
+ * ```
  */
 type PredicateMap = Record<string, Predicate>;
 /**
  * A map of function names to generic functions, used elsewhere in the system.
+ *
+ * @example
+ * ```typescript
+ * const functionMap: FunctionMap = {
+ *    calculateTotal: (items: { price: number; quantity: number }[]) => {
+ *        return items.reduce((acc, item) => acc + item.price * item.quantity, 0);
+ *    }
+ * };
+ * ```
  */
 type FunctionMap = Record<string, Function>;
 /** @deprecated Use PredicateMap instead. */
 type ConstraintsMap = Record<string, Predicate>;
 /**
  * Names of supported predicates, derived from a PredicateMap.
+ *
+ * @example
+ * ```typescript
+ * type AvailablePredicates = PredicateName<typeof predicateMap>; // "isEmail" | "isPositive"
+ * ```
  */
 type PredicateName<T extends PredicateMap = any> = keyof T;
 /**
  * Parameters for predicates, tailored to each field type.
+ *
+ * @example
+ * ```typescript
+ * type StringParams = PredicateParameters<"string">; // string | string[] | RegExp | { field: string }
+ * type NumberParams = PredicateParameters<"number">; // number | number[] | { precision: number; scale?: number } | { field: string }
+ * ```
  */
 type PredicateParameters<T extends FieldType> = T extends "string" ? string | string[] | RegExp | {
     field: string;
@@ -217,6 +260,16 @@ type PredicateParameters<T extends FieldType> = T extends "string" ? string | st
 type ConstraintParameters<T extends FieldType> = PredicateParameters<T>;
 /**
  * Defines a constraint on a field or schema, using a predicate for validation.
+ *
+ * @example
+ * ```typescript
+ * const emailConstraint: Constraint<"string"> = {
+ *    name: "email",
+ *    predicate: "isEmail",
+ *    parameters: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+ *    errorMessage: "Must be a valid email address."
+ * };
+ * ```
  */
 type Constraint<T extends FieldType> = {
     type?: "schema";
@@ -229,6 +282,18 @@ type Constraint<T extends FieldType> = {
 };
 /**
  * Groups multiple constraints with a logical operator for complex validation logic.
+ *
+ * @example
+ * ```typescript
+ * const compositeConstraint: ConstraintGroup<"number"> = {
+ *    name: "positiveAndLessThan100",
+ *    operator: "and",
+ *    rules: [
+ *        { name: "positive", predicate: "isPositive", parameters: 0 },
+ *        { name: "lessThan100", predicate: "isLessThan", parameters: 100 }
+ *    ]
+ * };
+ * ```
  */
 interface ConstraintGroup<T extends FieldType> {
     name: string;
@@ -237,6 +302,14 @@ interface ConstraintGroup<T extends FieldType> {
 }
 /**
  * Collection of constraints or groups applied at the schema or nested level.
+ *
+ * @example
+ * ```typescript
+ * const schemaConstraints: SchemaConstraint<"number"> = [
+ *    { name: "positive", predicate: "isPositive", parameters: 0 },
+ *    compositeConstraint
+ * ];
+ * ```
  */
 type SchemaConstraint<T extends FieldType> = Array<Constraint<T> | ConstraintGroup<T>>;
 /** Reference to a nested schema (mini-SchemaDefinition) with optional overrides. */
@@ -247,6 +320,23 @@ interface FieldSchema {
 }
 /**
  * Defines a field within a schema, including its type, constraints, and nesting.
+ *
+ * @example
+ * ```typescript
+ * const ageField: FieldDefinition<number> = {
+ *    name: "age",
+ *    type: "number",
+ *    required: true,
+ *    constraints: [{ name: "positive", predicate: "isPositive", parameters: 0 }],
+ *    default: 25,
+ *    hint: {
+ *        input: {
+ *            min : 0,
+ *            max : 100
+ *        }
+ *    }
+ * };
+ * ```
  */
 interface FieldDefinition<T> {
     name: string;
@@ -257,7 +347,7 @@ interface FieldDefinition<T> {
     /** For type 'enum', specifies the allowed values. */
     values?: Array<string | number>;
     /** For type 'union', specifies the array of allowed schemas.
-     *  For type 'object' specifies the schema of the object
+     * For type 'object' specifies the schema of the object
      * */
     schema?: FieldSchema | Array<FieldSchema>;
     itemsType?: FieldType;
@@ -275,6 +365,15 @@ interface FieldDefinition<T> {
 }
 /**
  * Condition for partial indexes, allowing conditional indexing based on field values.
+ *
+ * @example
+ * ```typescript
+ * const activeCondition: PartialIndexCondition = {
+ *    operator: "and",
+ *    field: "isActive",
+ *    value: true
+ * };
+ * ```
  */
 interface PartialIndexCondition {
     operator: LogicalOperator;
@@ -284,6 +383,16 @@ interface PartialIndexCondition {
 }
 /**
  * Defines an index for optimizing queries or enforcing uniqueness.
+ *
+ * @example
+ * ```typescript
+ * const nameIndex: IndexDefinition = {
+ *    name: "nameIndex",
+ *    fields: ["firstName", "lastName"],
+ *    type: "composite",
+ *    unique: true
+ * };
+ * ```
  */
 interface IndexDefinition {
     fields: string[];
@@ -300,6 +409,27 @@ interface IndexDefinition {
  * but only when concrete is false. This restriction avoids complexity in RDBMS implementations,
  * where concrete schemas map directly to tables with fixed columns. Non-concrete schemas, as embedded
  * structures, can leverage this flexibility without affecting physical table design.
+ *
+ * @example
+ * ```typescript
+ * const addressSchema: NestedSchemaDefinition = {
+ *    name: "address",
+ *    fields: {
+ *        street: { name: "street", type: "string" },
+ *        city: { name: "city", type: "string" },
+ *        zip: { name: "zip", type: "string" }
+ *    },
+ *    concrete: true
+ * };
+ *
+ * const contactSchema: NestedSchemaDefinition = {
+ *    name: "contact",
+ *    fields: [
+ *        { fields: { email: { name: "email", type: "string" } }, when: { field: "type", value: "email" } },
+ *        { fields: { phone: { name: "phone", type: "string" } }, when: { field: "type", value: "phone" } }
+ *    ]
+ * };
+ * ```
  */
 interface NestedSchemaDefinition {
     /**
@@ -321,8 +451,8 @@ interface NestedSchemaDefinition {
      * Defines the fields of the nested schema.
      * - If concrete is true, must be a Record<string, FieldDefinition<any>> for a fixed field set.
      * - If concrete is false, can be either a Record<string, FieldDefinition<any>> or an
-     *   Array<{ fields: Record<string, FieldDefinition<any>>; when?: { field: string; value: any } }>,
-     *   allowing discriminated field sets based on a field value (e.g., 'type').
+     * Array<{ fields: Record<string, FieldDefinition<any>>; when?: { field: string; value: any } }>,
+     * allowing discriminated field sets based on a field value (e.g., 'type').
      * The array form enables variant-specific fields without constraints, but is not supported for
      * concrete schemas to maintain simplicity in RDBMS table mappings.
      */
@@ -343,6 +473,34 @@ interface NestedSchemaDefinition {
 }
 /**
  * Defines a complete schema, intended as an atomic unit within a larger domain model.
+ *
+ * @example
+ * ```typescript
+ * const userSchema: SchemaDefinition = {
+ *    name: "user",
+ *    version: "1.0.0",
+ *    fields: {
+ *        id: { name: "id", type: "string", required: true },
+ *        name: { name: "name", type: "string" },
+ *        address: { name: "address", type: "object", schema: { id: "address" } }
+ *    },
+ *    nestedSchemas: {
+ *        address: addressSchema
+ *    },
+ *    indexes: [{ name: "nameIndex", fields: ["name"], type: "normal" }],
+ *    mock: (faker) => {
+ *        return {
+ *            id: faker.string.uuid(),
+ *            name: faker.person.fullName(),
+ *            address: {
+ *                street: faker.location.streetAddress(),
+ *                city: faker.location.city(),
+ *                zip: faker.location.zipCode()
+ *            }
+ *        };
+ *    }
+ * };
+ * ```
  */
 interface SchemaDefinition {
     name: string;
@@ -363,6 +521,25 @@ interface SchemaDefinition {
 /**
  * Defines a change that can be made to a schema during migration.
  * Updated to support the new NestedSchemaDefinition structure.
+ *
+ * @example
+ * ```typescript
+ * const addEmailField: SchemaChange<string> = {
+ *    type: "addField",
+ *    id: "email",
+ *    definition: { name: "email", type: "string" }
+ * };
+ *
+ * const modifyAddressSchema: SchemaChange<any> = {
+ *    type: "modifyNestedSchema",
+ *    id: "address",
+ *    changes: {
+ *        fields: {
+ *            country: {name: "country", type: "string"}
+ *        }
+ *    }
+ * }
+ * ```
  */
 type SchemaChange<T> = {
     type: "modifyProperty";
@@ -421,10 +598,25 @@ type SchemaChange<T> = {
 };
 /**
  * Defines a transform function for data migration between schema versions.
+ *
+ * @example
+ * ```typescript
+ * const transformEmail: TransformFunction<{ oldEmail: string }, { email: string }> = (data) => {
+ * return { email: data.oldEmail };
+ * };
+ * ```
  */
 type TransformFunction<Initial, Next> = (data: Initial) => Next | Promise<Next>;
 /**
  * Represents a pair of transformations for bidirectional data migration.
+ *
+ * @example
+ * ```typescript
+ * const emailMigration: DataTransform<{ oldEmail: string }, { email: string }> = {
+ * forward: transformEmail,
+ * backward: (data) => ({ oldEmail: data.email })
+ * };
+ * ```
  */
 interface DataTransform<Initial, Next> {
     forward: TransformFunction<Initial, Next>;
@@ -432,6 +624,20 @@ interface DataTransform<Initial, Next> {
 }
 /**
  * Defines a migration, consisting of schema changes and data transforms.
+ *
+ * @example
+ * ```typescript
+ * const emailMigration: Migration<string> = {
+ * id: "emailMigration",
+ * schemaVersion: "2.0.0",
+ * changes: [addEmailField],
+ * description: "Adds email field",
+ * status: "pending",
+ * transform: emailMigration,
+ * createdAt: new Date().toISOString(),
+ * checksum: "someChecksum"
+ * };
+ * ```
  */
 interface Migration<T> {
     id: string;
@@ -448,6 +654,13 @@ interface Migration<T> {
 }
 /**
  * Generator type for mock data functions (used with Faker).
+ *
+ * @example
+ * ```typescript
+ * const mockGenerator: Generator<{ name: string }, void, unknown> = function* (faker) {
+ * yield { name: faker.person.fullName() };
+ * };
+ * ```
  */
 type Generator<T, TReturn, TNext> = Iterator<T, TReturn, TNext>;
 
@@ -1536,6 +1749,37 @@ declare function validateSchemaDefinition(schema: unknown): schema is SchemaDefi
  */
 declare const validate: typeof validateSchemaDefinition;
 
+/**
+ * Represents a group of field definitions with optional metadata.
+ */
+interface FieldGroup {
+    name: string;
+    label: string;
+    description?: string;
+    fields: FieldDefinition<any>[];
+}
+/**
+ * Extracts all field definitions from a schema, organized into groups based on hint.input.group,
+ * including those in nested schemas, with proper path prefixing to represent the field hierarchy.
+ *
+ * @param schema - The schema definition to extract fields from
+ * @returns Array of field groups, each containing grouped field definitions
+ */
+declare function extractInputFieldGroups(schema: SchemaDefinition): FieldGroup[];
+/**
+ * Generates a default data object from a schema definition, ensuring all fields have values.
+ * Fields with explicit defaults use those values; otherwise, type-based defaults are applied.
+ * An optional resolver can override type-based defaults for fields without explicit defaults.
+ *
+ * @param schema - The schema definition to generate defaults from
+ * @param options - Optional configuration for custom defaults and discriminators
+ * @returns A fully populated default object conforming to the schema's structure
+ */
+declare function schemaDefaults<T>(schema: SchemaDefinition, options?: {
+    resolver?: (field: FieldDefinition<any>) => any;
+    discriminator?: Record<string, any>;
+}): T;
+
 /**
  * Generates a SHA-256 hash of the input string.
  *
@@ -1559,7 +1803,8 @@ declare function deepMerge<T extends object>(target: T, update: Partial<T>): T;
  * nested schemas, and union types for enum fields and constraints. Uses field.name as-is for field names,
  * capitalized nestedSchema.name for type names, and handles required/optional fields, new types (enum,
  * record, union), discriminated unions with common fields, primitives, arrays, sets, references, and nested
- * structures with strict type safety. Introduces unique generics for each record field.
+ * structures with strict type safety. Introduces unique generics for each record field and adjusts object
+ * fields referencing concrete schemas to use a string | NestedType union.
  *
  * @param schema - The schema definition to convert
  * @param includeComments - Whether to include JSDoc comments (default: true)
@@ -1567,10 +1812,6 @@ declare function deepMerge<T extends object>(target: T, update: Partial<T>): T;
  * @returns TypeScript type definitions as a string
  */
 declare function schemaToTypes(schema: SchemaDefinition, includeComments?: boolean, exportTypes?: boolean): string;
-/**
- * Generates a TypeScript interface for validating schema data
- */
-declare function generateValidationInterface(schema: SchemaDefinition, exportType?: boolean): string;
 
 /**
  * Serializes constraint parameters for error messages, handling special types like RegExp.
@@ -1615,22 +1856,4 @@ declare function docgen(schema: SchemaDefinition, options?: {
     faker?: Faker;
 }): string;
 
-/**
- * Represents a group of field definitions with optional metadata.
- */
-interface FieldGroup {
-    name: string;
-    label: string;
-    description?: string;
-    fields: FieldDefinition<any>[];
-}
-/**
- * Extracts all field definitions from a schema, organized into groups based on hint.input.group,
- * including those in nested schemas, with proper path prefixing to represent the field hierarchy.
- *
- * @param schema - The schema definition to extract fields from
- * @returns Array of field groups, each containing grouped field definitions
- */
-declare function extractInputFieldGroups(schema: SchemaDefinition): FieldGroup[];
-
-export { type ArrayHint, type BooleanHint, type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type DateHint, type DynamicHint, type EnumHint, type FieldDefinition, type FieldGroup, type FieldSchema, type FieldType, type FileHint, type FunctionMap, type GroupDefinition, type IndexDefinition, type IndexType, type InputHint, JsonPatchError, type LogicalOperator, type Migration, MigrationEngine, type MigrationEngineInterface, MigrationError, MigrationErrorCode, type MigrationMetadata, type NestedSchemaDefinition, type NumberHint, type ObjectHint, type PartialIndexCondition, type PatchOperation, type Persistence, type PersistenceCollection, type PersistenceEvent, type PersistenceEventType, type PersistenceTransaction, type Predicate, type PredicateMap, type PredicateName, type PredicateParameters, type RegistryLock, type RegistryMetadata, type RemoteRepository, type Schema, type SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaEvent, type SchemaEventType, type SchemaHint, type SchemaIndex, type SchemaMetadata, type SchemaMigrationHelper, SchemaRegistry, type SchemaRegistryInterface, type SchemaVersion, type SecretHint, type SetHint, type TextHint, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createGitSchemaRegistry, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, docgen, extractInputFieldGroups, formResolver, generateSHA256Hash, generateValidationInterface, normalizePath, schemaChangeToPatch, schemaToTypes, serializeParams, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };
+export { type ArrayHint, type BooleanHint, type Constraint, type ConstraintGroup, type ConstraintParameters, type ConstraintsMap, type DataTransform, type DateHint, type DynamicHint, type EnumHint, type FieldDefinition, type FieldGroup, type FieldSchema, type FieldType, type FileHint, type FunctionMap, type GroupDefinition, type IndexDefinition, type IndexType, type InputHint, JsonPatchError, type LogicalOperator, type Migration, MigrationEngine, type MigrationEngineInterface, MigrationError, MigrationErrorCode, type MigrationMetadata, type NestedSchemaDefinition, type NumberHint, type ObjectHint, type PartialIndexCondition, type PatchOperation, type Persistence, type PersistenceCollection, type PersistenceEvent, type PersistenceEventType, type PersistenceTransaction, type Predicate, type PredicateMap, type PredicateName, type PredicateParameters, type RegistryLock, type RegistryMetadata, type RemoteRepository, type Schema, type SchemaChange, type SchemaConstraint, type SchemaDefinition, type SchemaEvent, type SchemaEventType, type SchemaHint, type SchemaIndex, type SchemaMetadata, type SchemaMigrationHelper, SchemaRegistry, type SchemaRegistryInterface, type SchemaVersion, type SecretHint, type SetHint, type TextHint, type TransformFunction, applyPatch, calculateNextVersion, compareSemanticVersions, createGitSchemaRegistry, createPatch, createSchemaMigrationHelper, createStandardSchemaValidator, deepMerge, docgen, extractInputFieldGroups, formResolver, generateSHA256Hash, normalizePath, schemaChangeToPatch, schemaDefaults, schemaToTypes, serializeParams, sortSemanticVars, validate, validateMigration, validateSchemaChange, validateSchemaDefinition };