@asaidimu/anansi 2.0.0 → 3.0.0

package/index.d.cts

@@ -416,66 +416,6 @@ interface IndexDefinition {
  * Nested schemas are stored in the `nestedSchemas` map of a `SchemaDefinition` and referenced by their `id`.
  * They facilitate schema reusability, modularity, and the definition of polymorphic structures.
  *
- * @template T - The TypeScript type this schema represents. When `literal` is `true`, this `T`
- * corresponds to the actual primitive type (e.g., `string`, `number`).
- * When `literal` is `false`, `T` is typically an object type.
- *
- * @example
- * // Example of a concrete, object-based nested schema (like a fixed address structure)
- * ```typescript
- * const addressSchema: NestedSchemaDefinition = {
- * name: "AddressSchema",
- * description: "A concrete schema for geographical addresses.",
- * fields: {
- * street: { name: "street", type: "string", description: "Street name and number." },
- * city: { name: "city", type: "string", description: "City or town." },
- * zip: { name: "zip", type: "string", description: "Postal or zip code." }
- * },
- * concrete: true // Suitable for RDBMS table mapping
- * };
- * ```
- *
- * @example
- * // Example of a non-concrete, object-based nested schema with discriminated fields (like a contact method)
- * ```typescript
- * const contactSchema: NestedSchemaDefinition = {
- * name: "ContactMethod",
- * description: "Represents various contact methods using a discriminated union.",
- * fields: [
- * {
- * fields: {
- * type: { name: "type", type: "enum", values: ["email"], required: true },
- * email: { name: "email", type: "string", hint: { input: { type: "email" } } }
- * },
- * when: { field: "type", value: "email" }
- * },
- * {
- * fields: {
- * type: { name: "type", type: "enum", values: ["phone"], required: true },
- * phone: { name: "phone", type: "string", hint: { input: { type: "tel" } } }
- * },
- * when: { field: "type", value: "phone" }
- * }
- * ],
- * concrete: false // Allows for discriminated field sets
- * };
- * ```
- *
- * @example
- * // Example of a literal nested schema (reusable email string definition)
- * ```typescript
- * const emailStringSchema: NestedSchemaDefinition<string> = {
- * name: "EmailAddressString",
- * description: "A literal schema for a validated email address string.",
- * literal: true,
- * type: "string",
- * constraints: {
- * predicates: {
- * matches: "/^[^\s@]+@[^\s@]+\\.[^\s@]+$/" // Regex for email format validation
- * }
- * }
- * };
- * ```
  */
 type NestedSchemaDefinition<T> = {
     /**
@@ -489,52 +429,27 @@ type NestedSchemaDefinition<T> = {
      * This is crucial for documentation and understanding the schema's intent.
      */
     description?: string;
-} & (
-/**
- * Defines a literal nested schema.
- * When `literal` is `true`, this `NestedSchemaDefinition` represents a direct primitive value
- * (string, number, or boolean) rather than an object with fields.
- * This is particularly useful for:
- * - Defining reusable primitive types with specific constraints (e.g., a regex for an "EmailAddress" string).
- * - Enabling direct unions between primitive types and object types within a `FieldDefinition`
- * (e.g., `FieldType: "union"`, where one `FieldSchema` references a literal type).
- */
-{
-    literal: true;
     /**
-     * The basic primitive type that this literal schema represents.
-     * Must be one of "string", "number", or "boolean".
-     */
-    type: "string" | "number" | "boolean";
-    /**
-     * An optional default value for this literal schema.
-     * If provided, the type of `default` must strictly match the `type` specified.
-     * @example "default@example.com" for type "string"
-     * @example 0 for type "number"
-     */
-    default?: T;
-    /**
-     * Optional constraints for additional validation rules specific to this literal type.
-     * These constraints apply directly to the primitive value.
+     * Defines database indexes for the fields within this nested schema.
+     * This is primarily applicable when `concrete` is `true`, indicating that the schema
+     * maps directly to a persistent data store table. Indexes help optimize data retrieval.
      */
-    constraints?: Array<Constraint<any> | ConstraintGroup<any>>;
+    indexes?: IndexDefinition[];
     /**
-     * Optional generic metadata associated with the literal schema.
-     * This can store any additional information relevant to tooling or specific domain requirements.
-     * @example `{ uiComponent: "emailInput", validationMessage: "Invalid email format" }`
+     * Optional generic metadata associated with the structured schema.
+     * This can store any additional information relevant to tooling, UI generation,
+     * or specific domain requirements that are not covered by other properties.
+     * @example `{ graphqlType: "Address", apiEndpoint: "/api/addresses" }`
      */
     metadata?: Record<string, any>;
-} | 
-/**
- * Defines a structured nested schema that represents an object with defined fields.
- * This is the traditional way of defining complex data structures within the schema.
- */
-{
+} & ({
     /**
-     * Explicitly indicates that this is a non-literal, structured schema.
-     * Default value is `false` if omitted.
+     * Optional constraints for additional validation rules that apply to the entire structured schema.
+     * These constraints provide an extra layer of data integrity beyond basic type checking.
+     * They are less strictly necessary when using discriminated field sets (`fields` as an array),
+     * as much of the variant logic can be enforced structurally through the `when` clauses.
      */
-    literal?: false;
+    constraints?: SchemaConstraint<any>;
     /**
      * Indicates whether this schema represents a standalone entity (`true`) or is embedded (`false`).
      * - When `true` (`concrete: true`), the schema is treated as a distinct, fixed-structure entity,
@@ -579,27 +494,12 @@ type NestedSchemaDefinition<T> = {
             value: any;
         };
     }>;
+} | (Pick<FieldDefinition<T>, "name" | "default" | "schema" | "itemsType" | "constraints"> & {
     /**
-     * Optional constraints for additional validation rules that apply to the entire structured schema.
-     * These constraints provide an extra layer of data integrity beyond basic type checking.
-     * They are less strictly necessary when using discriminated field sets (`fields` as an array),
-     * as much of the variant logic can be enforced structurally through the `when` clauses.
-     */
-    constraints?: SchemaConstraint<any>;
-    /**
-     * Defines database indexes for the fields within this nested schema.
-     * This is primarily applicable when `concrete` is `true`, indicating that the schema
-     * maps directly to a persistent data store table. Indexes help optimize data retrieval.
-     */
-    indexes?: IndexDefinition[];
-    /**
-     * Optional generic metadata associated with the structured schema.
-     * This can store any additional information relevant to tooling, UI generation,
-     * or specific domain requirements that are not covered by other properties.
-     * @example `{ graphqlType: "Address", apiEndpoint: "/api/addresses" }`
+     * The basic primitive type that this literal schema represents.
      */
-    metadata?: Record<string, any>;
-});
+    type: "string" | "number" | "boolean" | "array" | "set" | "enum" | "record";
+}));
 /**
  * Defines a complete schema, intended as an atomic unit within a larger domain model.
  *

package/index.d.ts

@@ -416,66 +416,6 @@ interface IndexDefinition {
  * Nested schemas are stored in the `nestedSchemas` map of a `SchemaDefinition` and referenced by their `id`.
  * They facilitate schema reusability, modularity, and the definition of polymorphic structures.
  *
- * @template T - The TypeScript type this schema represents. When `literal` is `true`, this `T`
- * corresponds to the actual primitive type (e.g., `string`, `number`).
- * When `literal` is `false`, `T` is typically an object type.
- *
- * @example
- * // Example of a concrete, object-based nested schema (like a fixed address structure)
- * ```typescript
- * const addressSchema: NestedSchemaDefinition = {
- * name: "AddressSchema",
- * description: "A concrete schema for geographical addresses.",
- * fields: {
- * street: { name: "street", type: "string", description: "Street name and number." },
- * city: { name: "city", type: "string", description: "City or town." },
- * zip: { name: "zip", type: "string", description: "Postal or zip code." }
- * },
- * concrete: true // Suitable for RDBMS table mapping
- * };
- * ```
- *
- * @example
- * // Example of a non-concrete, object-based nested schema with discriminated fields (like a contact method)
- * ```typescript
- * const contactSchema: NestedSchemaDefinition = {
- * name: "ContactMethod",
- * description: "Represents various contact methods using a discriminated union.",
- * fields: [
- * {
- * fields: {
- * type: { name: "type", type: "enum", values: ["email"], required: true },
- * email: { name: "email", type: "string", hint: { input: { type: "email" } } }
- * },
- * when: { field: "type", value: "email" }
- * },
- * {
- * fields: {
- * type: { name: "type", type: "enum", values: ["phone"], required: true },
- * phone: { name: "phone", type: "string", hint: { input: { type: "tel" } } }
- * },
- * when: { field: "type", value: "phone" }
- * }
- * ],
- * concrete: false // Allows for discriminated field sets
- * };
- * ```
- *
- * @example
- * // Example of a literal nested schema (reusable email string definition)
- * ```typescript
- * const emailStringSchema: NestedSchemaDefinition<string> = {
- * name: "EmailAddressString",
- * description: "A literal schema for a validated email address string.",
- * literal: true,
- * type: "string",
- * constraints: {
- * predicates: {
- * matches: "/^[^\s@]+@[^\s@]+\\.[^\s@]+$/" // Regex for email format validation
- * }
- * }
- * };
- * ```
  */
 type NestedSchemaDefinition<T> = {
     /**
@@ -489,52 +429,27 @@ type NestedSchemaDefinition<T> = {
      * This is crucial for documentation and understanding the schema's intent.
      */
     description?: string;
-} & (
-/**
- * Defines a literal nested schema.
- * When `literal` is `true`, this `NestedSchemaDefinition` represents a direct primitive value
- * (string, number, or boolean) rather than an object with fields.
- * This is particularly useful for:
- * - Defining reusable primitive types with specific constraints (e.g., a regex for an "EmailAddress" string).
- * - Enabling direct unions between primitive types and object types within a `FieldDefinition`
- * (e.g., `FieldType: "union"`, where one `FieldSchema` references a literal type).
- */
-{
-    literal: true;
     /**
-     * The basic primitive type that this literal schema represents.
-     * Must be one of "string", "number", or "boolean".
-     */
-    type: "string" | "number" | "boolean";
-    /**
-     * An optional default value for this literal schema.
-     * If provided, the type of `default` must strictly match the `type` specified.
-     * @example "default@example.com" for type "string"
-     * @example 0 for type "number"
-     */
-    default?: T;
-    /**
-     * Optional constraints for additional validation rules specific to this literal type.
-     * These constraints apply directly to the primitive value.
+     * Defines database indexes for the fields within this nested schema.
+     * This is primarily applicable when `concrete` is `true`, indicating that the schema
+     * maps directly to a persistent data store table. Indexes help optimize data retrieval.
      */
-    constraints?: Array<Constraint<any> | ConstraintGroup<any>>;
+    indexes?: IndexDefinition[];
     /**
-     * Optional generic metadata associated with the literal schema.
-     * This can store any additional information relevant to tooling or specific domain requirements.
-     * @example `{ uiComponent: "emailInput", validationMessage: "Invalid email format" }`
+     * Optional generic metadata associated with the structured schema.
+     * This can store any additional information relevant to tooling, UI generation,
+     * or specific domain requirements that are not covered by other properties.
+     * @example `{ graphqlType: "Address", apiEndpoint: "/api/addresses" }`
      */
     metadata?: Record<string, any>;
-} | 
-/**
- * Defines a structured nested schema that represents an object with defined fields.
- * This is the traditional way of defining complex data structures within the schema.
- */
-{
+} & ({
     /**
-     * Explicitly indicates that this is a non-literal, structured schema.
-     * Default value is `false` if omitted.
+     * Optional constraints for additional validation rules that apply to the entire structured schema.
+     * These constraints provide an extra layer of data integrity beyond basic type checking.
+     * They are less strictly necessary when using discriminated field sets (`fields` as an array),
+     * as much of the variant logic can be enforced structurally through the `when` clauses.
      */
-    literal?: false;
+    constraints?: SchemaConstraint<any>;
     /**
      * Indicates whether this schema represents a standalone entity (`true`) or is embedded (`false`).
      * - When `true` (`concrete: true`), the schema is treated as a distinct, fixed-structure entity,
@@ -579,27 +494,12 @@ type NestedSchemaDefinition<T> = {
             value: any;
         };
     }>;
+} | (Pick<FieldDefinition<T>, "name" | "default" | "schema" | "itemsType" | "constraints"> & {
     /**
-     * Optional constraints for additional validation rules that apply to the entire structured schema.
-     * These constraints provide an extra layer of data integrity beyond basic type checking.
-     * They are less strictly necessary when using discriminated field sets (`fields` as an array),
-     * as much of the variant logic can be enforced structurally through the `when` clauses.
-     */
-    constraints?: SchemaConstraint<any>;
-    /**
-     * Defines database indexes for the fields within this nested schema.
-     * This is primarily applicable when `concrete` is `true`, indicating that the schema
-     * maps directly to a persistent data store table. Indexes help optimize data retrieval.
-     */
-    indexes?: IndexDefinition[];
-    /**
-     * Optional generic metadata associated with the structured schema.
-     * This can store any additional information relevant to tooling, UI generation,
-     * or specific domain requirements that are not covered by other properties.
-     * @example `{ graphqlType: "Address", apiEndpoint: "/api/addresses" }`
+     * The basic primitive type that this literal schema represents.
      */
-    metadata?: Record<string, any>;
-});
+    type: "string" | "number" | "boolean" | "array" | "set" | "enum" | "record";
+}));
 /**
  * Defines a complete schema, intended as an atomic unit within a larger domain model.
  *

package/package.json

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