@asaidimu/anansi 1.5.2 → 1.5.3

package/index.cjs

@@ -64,4 +64,4 @@ ${n.description}
 ## Migrations
 `),t.push("| ID | Description | Status | Changes |"),t.push("|----|-------------|--------|---------|");for(let a of n.migrations||[])t.push([a.id,a.description,a.status,a.changes.length].join("|"));if(n.mock&&e?.faker)try{let a=n.mock(e.faker).next().value;t.push("\n## Example Data\n```json\n"+JSON.stringify(a,null,2)+"\n```")}catch{t.push(`
 <!-- Error generating mock data -->`)}return t.join(`
-`)}function Et(n){let e={},t={};n.hint?.groups&&n.hint.groups.forEach(s=>{t[s.name]={label:s.label,description:s.description}}),Ge(n.fields,"",n.nestedSchemas||{},e);let i=[];for(let[s,r]of Object.entries(e)){let a=s!=="ungrouped"?t[s]:void 0;i.push({name:s!=="ungrouped"?s:"ungrouped",label:a?.label||"Ungrouped",description:a?.description,fields:r})}return i}function Ge(n,e,t,i){for(let[s,r]of Object.entries(n)){if(r.hint?.input?.ignore)continue;let a=e?`${e}.${r.name}`:r.name,o={...r,name:a},c=r.hint?.input?.group||"ungrouped";if(i[c]||(i[c]=[]),i[c].push(o),r.nestedSchema?.id&&t[r.nestedSchema.id]){let d=t[r.nestedSchema.id];Ge(d.fields,a,t,i)}}}0&&(module.exports={JsonPatchError,MigrationEngine,MigrationError,MigrationErrorCode,SchemaRegistry,applyPatch,calculateNextVersion,compareSemanticVersions,createGitSchemaRegistry,createPatch,createSchemaMigrationHelper,createStandardSchemaValidator,deepMerge,docgen,extractInputFieldGroups,generateSHA256Hash,generateValidationInterface,normalizePath,schemaChangeToPatch,schemaToTypes,serializeParams,sortSemanticVars,validate,validateMigration,validateSchemaChange,validateSchemaDefinition});
+`)}function Et(n){let e={},t={};n.hint?.groups&&n.hint.groups.forEach(s=>{t[s.name]={label:s.label,description:s.description}}),Ge(n.fields,"",n.nestedSchemas||{},e);let i=[];for(let[s,r]of Object.entries(e)){let a=s!=="ungrouped"?t[s]:void 0;i.push({name:s!=="ungrouped"?s:"ungrouped",label:a?.label||"Ungrouped",description:a?.description,fields:r})}return i}function Ge(n,e,t,i){for(let[s,r]of Object.entries(n)){let a=e?`${e}.${r.name}`:r.name,o={...r,name:a};if(!r.hint?.input?.ignore){if(r.type!=="object"){let c=r.hint?.input?.group||"ungrouped";i[c]||(i[c]=[]),i[c].push(o)}if(r.nestedSchema?.id&&t[r.nestedSchema.id]){let c=t[r.nestedSchema.id];Ge(c.fields,a,t,i)}}}}0&&(module.exports={JsonPatchError,MigrationEngine,MigrationError,MigrationErrorCode,SchemaRegistry,applyPatch,calculateNextVersion,compareSemanticVersions,createGitSchemaRegistry,createPatch,createSchemaMigrationHelper,createStandardSchemaValidator,deepMerge,docgen,extractInputFieldGroups,generateSHA256Hash,generateValidationInterface,normalizePath,schemaChangeToPatch,schemaToTypes,serializeParams,sortSemanticVars,validate,validateMigration,validateSchemaChange,validateSchemaDefinition});

package/index.d.cts

@@ -155,7 +155,7 @@ type LogicalOperator = "and" | "or" | "not" | "nor" | "xor";
 /**
  * Basic field types supported by the schema system.
  */
-type FieldType = "string" | "number" | "boolean" | "array" | "set" | "enum" | "object" | "record" | "dynamic";
+type FieldType = "string" | "number" | "boolean" | "array" | "set" | "enum" | "object" | "record" | "union" | "dynamic";
 /**
  * Index types for optimizing different query patterns.
  */
@@ -226,6 +226,12 @@ interface ConstraintGroup<T extends FieldType> {
  * Collection of constraints or groups applied at the schema or nested level.
  */
 type SchemaConstraint<T extends FieldType> = Array<Constraint<T> | ConstraintGroup<T>>;
+/** Reference to a nested schema (mini-SchemaDefinition) with optional overrides. */
+interface FieldSchema {
+    id: string;
+    constraints?: SchemaConstraint<any>;
+    indexes?: IndexDefinition[];
+}
 /**
  * Defines a field within a schema, including its type, constraints, and nesting.
  */
@@ -235,14 +241,14 @@ interface FieldDefinition<T> {
     required?: boolean;
     constraints?: Constraint<any>[];
     default?: T;
-    values?: Array<unknown>;
+    /** 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
+     * */
+    schema?: FieldSchema | Array<FieldSchema>;
     itemsType?: FieldType;
-    /** Reference to a nested schema (mini-SchemaDefinition) with optional overrides. */
-    nestedSchema?: {
-        id: string;
-        constraints?: SchemaConstraint<any>;
-        indexes?: IndexDefinition[];
-    };
+    nestedSchema?: FieldSchema;
     deprecated?: boolean;
     reference?: {
         schema: string;
@@ -276,15 +282,50 @@ interface IndexDefinition {
     name: string;
 }
 /**
- * A mini-schema definition for reusable nested structures within a larger schema.
- * Mirrors SchemaDefinition but omits top-level-only properties like version and migrations.
+ * Represents a nested schema definition embedded within a parent schema.
+ * Unlike SchemaDefinition, this can use a discriminated array of field sets for variant-specific fields,
+ * 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.
  */
 interface NestedSchemaDefinition {
+    /**
+     * The name of the nested schema, unique within the parent schema's nestedSchemas.
+     */
     name: string;
+    /**
+     * A description of the nested schema's purpose.
+     */
     description?: string;
-    fields: Record<string, FieldDefinition<any>>;
-    indexes?: IndexDefinition[];
+    /**
+     * Indicates whether this schema represents a standalone entity (true) or is embedded (false).
+     * When true, fields must be a Record<string, FieldDefinition<any>> to ensure a fixed structure
+     * suitable for RDBMS table mapping. When false, fields can be an array of discriminated field sets.
+     * @default false
+     */
+    concrete?: boolean;
+    /**
+     * 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').
+     * The array form enables variant-specific fields without constraints, but is not supported for
+     * concrete schemas to maintain simplicity in RDBMS table mappings.
+     */
+    fields: Record<string, FieldDefinition<any>> | Array<{
+        fields: Record<string, FieldDefinition<any>>;
+        when?: {
+            field: string;
+            value: any;
+        };
+    }>;
+    /**
+     * Optional constraints for additional validation rules.
+     * Less necessary when using discriminated field sets, as variant logic can be structural.
+     */
     constraints?: SchemaConstraint<any>;
+    indexes?: IndexDefinition[];
     metadata?: Record<string, any>;
 }
 /**

package/index.d.ts

@@ -155,7 +155,7 @@ type LogicalOperator = "and" | "or" | "not" | "nor" | "xor";
 /**
  * Basic field types supported by the schema system.
  */
-type FieldType = "string" | "number" | "boolean" | "array" | "set" | "enum" | "object" | "record" | "dynamic";
+type FieldType = "string" | "number" | "boolean" | "array" | "set" | "enum" | "object" | "record" | "union" | "dynamic";
 /**
  * Index types for optimizing different query patterns.
  */
@@ -226,6 +226,12 @@ interface ConstraintGroup<T extends FieldType> {
  * Collection of constraints or groups applied at the schema or nested level.
  */
 type SchemaConstraint<T extends FieldType> = Array<Constraint<T> | ConstraintGroup<T>>;
+/** Reference to a nested schema (mini-SchemaDefinition) with optional overrides. */
+interface FieldSchema {
+    id: string;
+    constraints?: SchemaConstraint<any>;
+    indexes?: IndexDefinition[];
+}
 /**
  * Defines a field within a schema, including its type, constraints, and nesting.
  */
@@ -235,14 +241,14 @@ interface FieldDefinition<T> {
     required?: boolean;
     constraints?: Constraint<any>[];
     default?: T;
-    values?: Array<unknown>;
+    /** 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
+     * */
+    schema?: FieldSchema | Array<FieldSchema>;
     itemsType?: FieldType;
-    /** Reference to a nested schema (mini-SchemaDefinition) with optional overrides. */
-    nestedSchema?: {
-        id: string;
-        constraints?: SchemaConstraint<any>;
-        indexes?: IndexDefinition[];
-    };
+    nestedSchema?: FieldSchema;
     deprecated?: boolean;
     reference?: {
         schema: string;
@@ -276,15 +282,50 @@ interface IndexDefinition {
     name: string;
 }
 /**
- * A mini-schema definition for reusable nested structures within a larger schema.
- * Mirrors SchemaDefinition but omits top-level-only properties like version and migrations.
+ * Represents a nested schema definition embedded within a parent schema.
+ * Unlike SchemaDefinition, this can use a discriminated array of field sets for variant-specific fields,
+ * 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.
  */
 interface NestedSchemaDefinition {
+    /**
+     * The name of the nested schema, unique within the parent schema's nestedSchemas.
+     */
     name: string;
+    /**
+     * A description of the nested schema's purpose.
+     */
     description?: string;
-    fields: Record<string, FieldDefinition<any>>;
-    indexes?: IndexDefinition[];
+    /**
+     * Indicates whether this schema represents a standalone entity (true) or is embedded (false).
+     * When true, fields must be a Record<string, FieldDefinition<any>> to ensure a fixed structure
+     * suitable for RDBMS table mapping. When false, fields can be an array of discriminated field sets.
+     * @default false
+     */
+    concrete?: boolean;
+    /**
+     * 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').
+     * The array form enables variant-specific fields without constraints, but is not supported for
+     * concrete schemas to maintain simplicity in RDBMS table mappings.
+     */
+    fields: Record<string, FieldDefinition<any>> | Array<{
+        fields: Record<string, FieldDefinition<any>>;
+        when?: {
+            field: string;
+            value: any;
+        };
+    }>;
+    /**
+     * Optional constraints for additional validation rules.
+     * Less necessary when using discriminated field sets, as variant logic can be structural.
+     */
     constraints?: SchemaConstraint<any>;
+    indexes?: IndexDefinition[];
     metadata?: Record<string, any>;
 }
 /**

package/index.js

@@ -64,4 +64,4 @@ ${n.description}
 ## Migrations
 `),t.push("| ID | Description | Status | Changes |"),t.push("|----|-------------|--------|---------|");for(let a of n.migrations||[])t.push([a.id,a.description,a.status,a.changes.length].join("|"));if(n.mock&&e?.faker)try{let a=n.mock(e.faker).next().value;t.push("\n## Example Data\n```json\n"+JSON.stringify(a,null,2)+"\n```")}catch{t.push(`
 <!-- Error generating mock data -->`)}return t.join(`
-`)}function yn(n){let e={},t={};n.hint?.groups&&n.hint.groups.forEach(s=>{t[s.name]={label:s.label,description:s.description}}),Me(n.fields,"",n.nestedSchemas||{},e);let i=[];for(let[s,r]of Object.entries(e)){let a=s!=="ungrouped"?t[s]:void 0;i.push({name:s!=="ungrouped"?s:"ungrouped",label:a?.label||"Ungrouped",description:a?.description,fields:r})}return i}function Me(n,e,t,i){for(let[s,r]of Object.entries(n)){if(r.hint?.input?.ignore)continue;let a=e?`${e}.${r.name}`:r.name,o={...r,name:a},c=r.hint?.input?.group||"ungrouped";if(i[c]||(i[c]=[]),i[c].push(o),r.nestedSchema?.id&&t[r.nestedSchema.id]){let d=t[r.nestedSchema.id];Me(d.fields,a,t,i)}}}export{P as JsonPatchError,ke as MigrationEngine,x as MigrationError,et as MigrationErrorCode,B as SchemaRegistry,X as applyPatch,De as calculateNextVersion,M as compareSemanticVersions,sn as createGitSchemaRegistry,at as createPatch,tt as createSchemaMigrationHelper,Ue as createStandardSchemaValidator,pe as deepMerge,ln as docgen,yn as extractInputFieldGroups,j as generateSHA256Hash,mn as generateValidationInterface,Oe as normalizePath,me as schemaChangeToPatch,fn as schemaToTypes,J as serializeParams,pt as sortSemanticVars,mt as validate,Ce as validateMigration,Te as validateSchemaChange,q as validateSchemaDefinition};
+`)}function yn(n){let e={},t={};n.hint?.groups&&n.hint.groups.forEach(s=>{t[s.name]={label:s.label,description:s.description}}),Me(n.fields,"",n.nestedSchemas||{},e);let i=[];for(let[s,r]of Object.entries(e)){let a=s!=="ungrouped"?t[s]:void 0;i.push({name:s!=="ungrouped"?s:"ungrouped",label:a?.label||"Ungrouped",description:a?.description,fields:r})}return i}function Me(n,e,t,i){for(let[s,r]of Object.entries(n)){let a=e?`${e}.${r.name}`:r.name,o={...r,name:a};if(!r.hint?.input?.ignore){if(r.type!=="object"){let c=r.hint?.input?.group||"ungrouped";i[c]||(i[c]=[]),i[c].push(o)}if(r.nestedSchema?.id&&t[r.nestedSchema.id]){let c=t[r.nestedSchema.id];Me(c.fields,a,t,i)}}}}export{P as JsonPatchError,ke as MigrationEngine,x as MigrationError,et as MigrationErrorCode,B as SchemaRegistry,X as applyPatch,De as calculateNextVersion,M as compareSemanticVersions,sn as createGitSchemaRegistry,at as createPatch,tt as createSchemaMigrationHelper,Ue as createStandardSchemaValidator,pe as deepMerge,ln as docgen,yn as extractInputFieldGroups,j as generateSHA256Hash,mn as generateValidationInterface,Oe as normalizePath,me as schemaChangeToPatch,fn as schemaToTypes,J as serializeParams,pt as sortSemanticVars,mt as validate,Ce as validateMigration,Te as validateSchemaChange,q as validateSchemaDefinition};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/anansi",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "A toolkit for advanced data modelling",
   "main": "index.js",
   "types": "index.d.ts",