@jaypie/fabric 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,1606 @@
+import { BadRequestError, ConfigurationError } from '@jaypie/errors';
+
+/**
+ * FabricModel - Core model vocabulary for @jaypie/fabric
+ *
+ * Defines the standard fields and structure for all fabric models.
+ * Provides a consistent, reusable vocabulary across applications.
+ */
+// =============================================================================
+// Field Name Constants
+// =============================================================================
+/**
+ * FabricModel field names as constants
+ * Useful for building queries, validation, and serialization
+ */
+const FABRIC_MODEL_FIELDS = {
+    // Content
+    CONTENT: "content",
+    METADATA: "metadata",
+    // Display
+    EMOJI: "emoji",
+    ICON: "icon",
+    // History
+    HISTORY: "history",
+    // Identity (optional)
+    ABBREVIATION: "abbreviation",
+    ALIAS: "alias",
+    DESCRIPTION: "description",
+    LABEL: "label",
+    NAME: "name",
+    XID: "xid",
+    // Identity (required)
+    ID: "id",
+    // Schema
+    CLASS: "class",
+    MODEL: "model",
+    TYPE: "type",
+    // Storage
+    SCOPE: "scope",
+    SEQUENCE: "sequence",
+    // Time
+    ARCHIVED_AT: "archivedAt",
+    CREATED_AT: "createdAt",
+    DELETED_AT: "deletedAt",
+    UPDATED_AT: "updatedAt",
+};
+/**
+ * Required fields for FabricModel
+ */
+const FABRIC_MODEL_REQUIRED_FIELDS = [
+    FABRIC_MODEL_FIELDS.CREATED_AT,
+    FABRIC_MODEL_FIELDS.ID,
+    FABRIC_MODEL_FIELDS.MODEL,
+    FABRIC_MODEL_FIELDS.UPDATED_AT,
+];
+/**
+ * Auto-generated fields (set by store, not by user)
+ */
+const FABRIC_MODEL_AUTO_FIELDS = [
+    FABRIC_MODEL_FIELDS.CREATED_AT,
+    FABRIC_MODEL_FIELDS.HISTORY,
+    FABRIC_MODEL_FIELDS.ID,
+    FABRIC_MODEL_FIELDS.UPDATED_AT,
+];
+/**
+ * Timestamp fields
+ */
+const FABRIC_MODEL_TIMESTAMP_FIELDS = [
+    FABRIC_MODEL_FIELDS.ARCHIVED_AT,
+    FABRIC_MODEL_FIELDS.CREATED_AT,
+    FABRIC_MODEL_FIELDS.DELETED_AT,
+    FABRIC_MODEL_FIELDS.UPDATED_AT,
+];
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Check if a value is a FabricModel
+ */
+function isFabricModel(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (obj.createdAt instanceof Date &&
+        typeof obj.id === "string" &&
+        typeof obj.model === "string" &&
+        obj.updatedAt instanceof Date);
+}
+/**
+ * Check if a value has the minimum FabricModel shape (for partial objects)
+ */
+function hasFabricModelShape(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    return typeof obj.id === "string" && typeof obj.model === "string";
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Create a minimal FabricModelInput with required fields
+ */
+function createFabricModelInput(overrides) {
+    return {
+        ...overrides,
+    };
+}
+/**
+ * Extract only FabricModel fields from an object
+ * Useful for sanitizing input or preparing for storage
+ */
+function pickFabricModelFields(obj) {
+    const fields = Object.values(FABRIC_MODEL_FIELDS);
+    const result = {};
+    for (const field of fields) {
+        if (field in obj) {
+            result[field] = obj[field];
+        }
+    }
+    return result;
+}
+/**
+ * Check if a field name is a timestamp field
+ */
+function isTimestampField(field) {
+    return FABRIC_MODEL_TIMESTAMP_FIELDS.includes(field);
+}
+/**
+ * Check if a field name is auto-generated
+ */
+function isAutoField(field) {
+    return FABRIC_MODEL_AUTO_FIELDS.includes(field);
+}
+
+/**
+ * Meta-modeling Constants
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/** Root organizational unit */
+const APEX = "@";
+/** Fabric version - used to identify pre-instantiated Services */
+const FABRIC_VERSION = "0.1.0";
+/** Composite key separator */
+const SEPARATOR = "#";
+/** System-level models that describe other models */
+const SYSTEM_MODELS = ["context", "field", "model"];
+
+/**
+ * Date Type Conversion for @jaypie/fabric
+ *
+ * Adds Date as a supported type in the fabric type system.
+ * Follows the same conversion patterns as String, Number, Boolean.
+ */
+/**
+ * Check if a value is a valid Date
+ */
+function isValidDate(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime());
+}
+/**
+ * Convert a value to a Date
+ *
+ * Supported inputs:
+ * - Date: returned as-is (validated)
+ * - Number: treated as Unix timestamp (milliseconds)
+ * - String: parsed via Date constructor (ISO 8601, etc.)
+ * - Object with value property: unwrapped and converted
+ *
+ * @throws BadRequestError if value cannot be converted to valid Date
+ */
+function fabricDate(value) {
+    // Already a Date
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new BadRequestError("Invalid Date value");
+        }
+        return value;
+    }
+    // Null/undefined
+    if (value === null || value === undefined) {
+        throw new BadRequestError("Cannot convert null or undefined to Date");
+    }
+    // Object with value property (fabric pattern)
+    if (typeof value === "object" && value !== null && "value" in value) {
+        return fabricDate(value.value);
+    }
+    // Number (timestamp in milliseconds)
+    if (typeof value === "number") {
+        if (Number.isNaN(value)) {
+            throw new BadRequestError("Cannot convert NaN to Date");
+        }
+        const date = new Date(value);
+        if (Number.isNaN(date.getTime())) {
+            throw new BadRequestError(`Cannot convert ${value} to Date`);
+        }
+        return date;
+    }
+    // String (ISO 8601 or parseable format)
+    if (typeof value === "string") {
+        // Empty string is invalid
+        if (value.trim() === "") {
+            throw new BadRequestError("Cannot convert empty string to Date");
+        }
+        const date = new Date(value);
+        if (Number.isNaN(date.getTime())) {
+            throw new BadRequestError(`Cannot convert "${value}" to Date`);
+        }
+        return date;
+    }
+    // Boolean cannot be converted to Date
+    if (typeof value === "boolean") {
+        throw new BadRequestError("Cannot convert boolean to Date");
+    }
+    // Arrays - attempt single element extraction
+    if (Array.isArray(value)) {
+        if (value.length === 1) {
+            return fabricDate(value[0]);
+        }
+        throw new BadRequestError(`Cannot convert array with ${value.length} elements to Date`);
+    }
+    throw new BadRequestError(`Cannot convert ${typeof value} to Date`);
+}
+/**
+ * Resolve a value from a Date to another type
+ *
+ * @param value - Date to convert
+ * @param targetType - Target type (String, Number)
+ */
+function resolveFromDate(value, targetType) {
+    if (!isValidDate(value)) {
+        throw new BadRequestError("Invalid Date value");
+    }
+    if (targetType === String) {
+        return value.toISOString();
+    }
+    if (targetType === Number) {
+        return value.getTime();
+    }
+    throw new BadRequestError(`Cannot convert Date to ${targetType}`);
+}
+/**
+ * Date type constant for use in fabricService input definitions
+ *
+ * Usage:
+ * ```typescript
+ * const handler = fabricService({
+ *   input: {
+ *     startDate: { type: Date },
+ *     endDate: { type: Date, default: undefined }
+ *   }
+ * });
+ * ```
+ */
+const DateType = Date;
+/**
+ * Type guard for Date type in schema definitions
+ */
+function isDateType(type) {
+    return type === Date;
+}
+
+// Fabric functions for @jaypie/fabric
+/**
+ * Try to parse a string as JSON if it looks like JSON
+ * Returns the parsed value or the original string if not JSON
+ */
+function tryParseJson(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+        (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            // Not valid JSON, return original
+            return value;
+        }
+    }
+    return value;
+}
+/**
+ * Unwrap arrays and objects to get to the scalar value
+ * - Single-element arrays unwrap to their element
+ * - Objects with value property unwrap to that value
+ * - Recursively unwraps nested structures
+ */
+function unwrapToScalar(value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    // Unwrap single-element arrays
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return undefined;
+        }
+        if (value.length === 1) {
+            return unwrapToScalar(value[0]);
+        }
+        throw new BadRequestError("Cannot convert multi-value array to scalar");
+    }
+    // Unwrap objects with value property
+    if (typeof value === "object") {
+        const obj = value;
+        if ("value" in obj) {
+            return unwrapToScalar(obj.value);
+        }
+        throw new BadRequestError("Object must have a value attribute");
+    }
+    return value;
+}
+/**
+ * Prepare a value for scalar conversion by parsing JSON strings and unwrapping
+ */
+function prepareForScalarConversion(value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    // Try to parse JSON strings
+    if (typeof value === "string") {
+        const parsed = tryParseJson(value);
+        if (parsed !== value) {
+            // Successfully parsed, unwrap the result
+            return unwrapToScalar(parsed);
+        }
+        return value;
+    }
+    // Unwrap arrays and objects
+    if (Array.isArray(value) || typeof value === "object") {
+        return unwrapToScalar(value);
+    }
+    return value;
+}
+/**
+ * Convert a value to a boolean
+ * - Arrays, objects, and JSON strings are unwrapped first
+ * - String "true" becomes true
+ * - String "false" becomes false
+ * - Strings that parse to numbers: positive = true, zero or negative = false
+ * - Numbers: positive = true, zero or negative = false
+ * - Boolean passes through
+ */
+function fabricBoolean(value) {
+    // Prepare value by parsing JSON and unwrapping arrays/objects
+    const prepared = prepareForScalarConversion(value);
+    if (prepared === undefined || prepared === null) {
+        return undefined;
+    }
+    if (typeof prepared === "boolean") {
+        return prepared;
+    }
+    if (typeof prepared === "string") {
+        if (prepared === "") {
+            return undefined;
+        }
+        const lower = prepared.toLowerCase();
+        if (lower === "true") {
+            return true;
+        }
+        if (lower === "false") {
+            return false;
+        }
+        // Try to parse as number
+        const num = parseFloat(prepared);
+        if (isNaN(num)) {
+            throw new BadRequestError(`Cannot convert "${prepared}" to Boolean`);
+        }
+        return num > 0;
+    }
+    if (typeof prepared === "number") {
+        if (isNaN(prepared)) {
+            throw new BadRequestError("Cannot convert NaN to Boolean");
+        }
+        return prepared > 0;
+    }
+    throw new BadRequestError(`Cannot convert ${typeof prepared} to Boolean`);
+}
+/**
+ * Convert a value to a number
+ * - Arrays, objects, and JSON strings are unwrapped first
+ * - String "" becomes undefined
+ * - String "true" becomes 1
+ * - String "false" becomes 0
+ * - Strings that parse to numbers use those values
+ * - Strings that parse to NaN throw BadRequestError
+ * - Boolean true becomes 1, false becomes 0
+ * - Number passes through
+ */
+function fabricNumber(value) {
+    // Prepare value by parsing JSON and unwrapping arrays/objects
+    const prepared = prepareForScalarConversion(value);
+    if (prepared === undefined || prepared === null) {
+        return undefined;
+    }
+    if (typeof prepared === "number") {
+        if (isNaN(prepared)) {
+            throw new BadRequestError("Cannot convert NaN to Number");
+        }
+        return prepared;
+    }
+    if (typeof prepared === "boolean") {
+        return prepared ? 1 : 0;
+    }
+    if (typeof prepared === "string") {
+        if (prepared === "") {
+            return undefined;
+        }
+        const lower = prepared.toLowerCase();
+        if (lower === "true") {
+            return 1;
+        }
+        if (lower === "false") {
+            return 0;
+        }
+        const num = parseFloat(prepared);
+        if (isNaN(num)) {
+            throw new BadRequestError(`Cannot convert "${prepared}" to Number`);
+        }
+        return num;
+    }
+    throw new BadRequestError(`Cannot convert ${typeof prepared} to Number`);
+}
+/**
+ * Convert a value to a string
+ * - Arrays, objects, and JSON strings are unwrapped first
+ * - String "" becomes undefined
+ * - Boolean true becomes "true", false becomes "false"
+ * - Number converts to string representation
+ * - String passes through
+ */
+function fabricString(value) {
+    // Prepare value by parsing JSON and unwrapping arrays/objects
+    const prepared = prepareForScalarConversion(value);
+    if (prepared === undefined || prepared === null) {
+        return undefined;
+    }
+    if (typeof prepared === "string") {
+        if (prepared === "") {
+            return undefined;
+        }
+        return prepared;
+    }
+    if (typeof prepared === "boolean") {
+        return prepared ? "true" : "false";
+    }
+    if (typeof prepared === "number") {
+        if (isNaN(prepared)) {
+            throw new BadRequestError("Cannot convert NaN to String");
+        }
+        return String(prepared);
+    }
+    throw new BadRequestError(`Cannot convert ${typeof prepared} to String`);
+}
+/**
+ * Convert a value to an array
+ * - Non-arrays become arrays containing that value
+ * - Arrays of a single value become that value (unwrapped)
+ * - Multi-value arrays throw BadRequestError
+ * - undefined/null become undefined
+ */
+function fabricArray(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        // Arrays pass through (single-element unwrapping happens when converting FROM array)
+        return value;
+    }
+    // Non-arrays become single-element arrays
+    return [value];
+}
+/**
+ * Resolve a value from an array to a scalar
+ * - Single-element arrays become that element
+ * - Multi-element arrays throw BadRequestError
+ * - Non-arrays pass through
+ */
+function resolveFromArray(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return undefined;
+        }
+        if (value.length === 1) {
+            return value[0];
+        }
+        throw new BadRequestError("Cannot convert multi-value array to scalar");
+    }
+    return value;
+}
+/**
+ * Convert a value to an object with a value property
+ * - Scalars become { value: scalar }
+ * - Arrays become { value: array }
+ * - Objects with a value attribute pass through
+ * - Objects without a value attribute throw BadRequestError
+ * - undefined/null become undefined
+ */
+function fabricObject(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    // Check if already an object (but not an array)
+    if (typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        if ("value" in obj) {
+            return obj;
+        }
+        throw new BadRequestError("Object must have a value attribute");
+    }
+    // Scalars and arrays become { value: ... }
+    return { value };
+}
+/**
+ * Resolve a value from an object to its value property
+ * - Objects with a value property return that value
+ * - Objects without a value throw BadRequestError
+ * - Scalars pass through
+ */
+function resolveFromObject(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        if ("value" in obj) {
+            return obj.value;
+        }
+        throw new BadRequestError("Object must have a value attribute");
+    }
+    return value;
+}
+/**
+ * Check if a type is a typed array (e.g., [String], [Number], [], etc.)
+ */
+function isTypedArrayType(type) {
+    return Array.isArray(type);
+}
+/**
+ * Split a string on comma or tab delimiters for typed array conversion.
+ * Only splits if the string contains commas or tabs.
+ * Returns the original value if not a string or no delimiters found.
+ */
+function splitStringForArray(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    // Check for comma or tab delimiters
+    if (value.includes(",")) {
+        return value.split(",").map((s) => s.trim());
+    }
+    if (value.includes("\t")) {
+        return value.split("\t").map((s) => s.trim());
+    }
+    return value;
+}
+/**
+ * Try to parse a string as JSON for array context.
+ * Returns parsed value if it's an array, otherwise returns original.
+ */
+function tryParseJsonArray(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    const trimmed = value.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not valid JSON, fall through
+        }
+    }
+    return value;
+}
+/**
+ * Get the element type from a typed array type
+ * Returns undefined for untyped arrays ([])
+ */
+function getArrayElementType(type) {
+    if (type.length === 0) {
+        return undefined; // Untyped array
+    }
+    const elementType = type[0];
+    // Handle constructor types
+    if (elementType === Boolean)
+        return "boolean";
+    if (elementType === Number)
+        return "number";
+    if (elementType === String)
+        return "string";
+    if (elementType === Object)
+        return "object";
+    // Handle string types
+    if (elementType === "boolean")
+        return "boolean";
+    if (elementType === "number")
+        return "number";
+    if (elementType === "string")
+        return "string";
+    if (elementType === "object")
+        return "object";
+    // Handle shorthand types
+    if (elementType === "")
+        return "string"; // "" shorthand for String
+    if (typeof elementType === "object" &&
+        elementType !== null &&
+        Object.keys(elementType).length === 0) {
+        return "object"; // {} shorthand for Object
+    }
+    throw new BadRequestError(`Unknown array element type: ${String(elementType)}`);
+}
+/**
+ * Convert a value to a typed array
+ * - Tries to parse JSON arrays first
+ * - Splits strings on comma/tab if present
+ * - Wraps non-arrays in an array
+ * - Converts each element to the specified element type
+ */
+function fabricTypedArray(value, elementType) {
+    // Try to parse JSON array first
+    let processed = tryParseJsonArray(value);
+    // If still a string, try to split on comma/tab
+    processed = splitStringForArray(processed);
+    // Convert to array (wraps non-arrays)
+    const array = fabricArray(processed);
+    if (array === undefined) {
+        return undefined;
+    }
+    // If no element type specified, return as-is
+    if (elementType === undefined) {
+        return array;
+    }
+    // Convert each element to the element type
+    return array.map((element, index) => {
+        try {
+            switch (elementType) {
+                case "boolean":
+                    return fabricBoolean(element);
+                case "number":
+                    return fabricNumber(element);
+                case "object":
+                    return fabricObject(element);
+                case "string":
+                    return fabricString(element);
+                default:
+                    throw new BadRequestError(`Unknown element type: ${elementType}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof BadRequestError) {
+                throw new BadRequestError(`Cannot convert array element at index ${index}: ${error.message}`);
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Fabric a value to the specified type
+ */
+function fabric(value, type) {
+    // Check for Date type first
+    if (isDateType(type)) {
+        return fabricDate(value);
+    }
+    // Check for typed array types
+    if (isTypedArrayType(type)) {
+        const elementType = getArrayElementType(type);
+        return fabricTypedArray(value, elementType);
+    }
+    const normalizedType = normalizeType(type);
+    switch (normalizedType) {
+        case "array":
+            return fabricArray(value);
+        case "boolean":
+            return fabricBoolean(value);
+        case "number":
+            return fabricNumber(value);
+        case "object":
+            return fabricObject(value);
+        case "string":
+            return fabricString(value);
+        default:
+            throw new BadRequestError(`Unknown type: ${String(type)}`);
+    }
+}
+/**
+ * Normalize type to string representation
+ */
+function normalizeType(type) {
+    if (type === Array || type === "array") {
+        return "array";
+    }
+    if (type === Boolean || type === "boolean") {
+        return "boolean";
+    }
+    if (type === Number || type === "number") {
+        return "number";
+    }
+    if (type === Object || type === "object") {
+        return "object";
+    }
+    if (type === String || type === "string") {
+        return "string";
+    }
+    throw new BadRequestError(`Unknown type: ${String(type)}`);
+}
+
+/**
+ * Fallback Resolution Helper
+ *
+ * Resolves a field value with a fallback chain.
+ */
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Resolve a field value with fallbacks
+ *
+ * @param entity - The entity to read from
+ * @param field - The primary field name
+ * @param fallbacks - Fallback field names in priority order
+ * @returns First defined value, or undefined
+ *
+ * @example
+ * ```typescript
+ * const model = { title: undefined, name: "My Model", description: "A description" };
+ * resolveWithFallback(model, "title", ["name", "description"]);
+ * // Returns "My Model"
+ * ```
+ */
+function resolveWithFallback(entity, field, fallbacks = []) {
+    // Check primary field
+    if (entity[field] !== undefined) {
+        return entity[field];
+    }
+    // Check fallbacks in order
+    for (const fallback of fallbacks) {
+        if (entity[fallback] !== undefined) {
+            return entity[fallback];
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Resolved Name Helper
+ *
+ * Computes a resolved name from model fields using a priority chain.
+ */
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Compute resolved name from model fields
+ *
+ * Priority: name > alias > abbreviation > description
+ * Result is lowercase for consistent sorting/indexing
+ *
+ * @param model - The model to compute the resolved name from
+ * @returns The resolved name (lowercase) or undefined if no name fields exist
+ */
+function computeResolvedName(model) {
+    const value = model.name || model.alias || model.abbreviation || model.description;
+    return value?.toLowerCase();
+}
+
+/**
+ * Index Types for @jaypie/fabric
+ *
+ * Declarative index definitions for DynamoDB single-table design.
+ * Models can specify their own indexes, and dynamodb will create
+ * GSIs and auto-detect which index to use for queries.
+ */
+// =============================================================================
+// Default Indexes
+// =============================================================================
+/**
+ * Default indexes for the DynamoDB GSI pattern.
+ * These are used when a model does not specify custom indexes.
+ */
+const DEFAULT_INDEXES = [
+    { name: "indexScope", pk: ["scope", "model"], sk: ["sequence"] },
+    {
+        name: "indexAlias",
+        pk: ["scope", "model", "alias"],
+        sk: ["sequence"],
+        sparse: true,
+    },
+    {
+        name: "indexClass",
+        pk: ["scope", "model", "class"],
+        sk: ["sequence"],
+        sparse: true,
+    },
+    {
+        name: "indexType",
+        pk: ["scope", "model", "type"],
+        sk: ["sequence"],
+        sparse: true,
+    },
+    {
+        name: "indexXid",
+        pk: ["scope", "model", "xid"],
+        sk: ["sequence"],
+        sparse: true,
+    },
+];
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Default sort key fields when sk is not specified
+ */
+const DEFAULT_SORT_KEY = ["sequence"];
+/**
+ * Suffix appended to index keys when model is archived
+ */
+const ARCHIVED_SUFFIX = "#archived";
+/**
+ * Suffix appended to index keys when model is deleted
+ */
+const DELETED_SUFFIX = "#deleted";
+
+/**
+ * Key Builder for @jaypie/fabric
+ *
+ * Builds composite keys from model fields and index definitions.
+ */
+// =============================================================================
+// Key Builders
+// =============================================================================
+/**
+ * Build a composite key from model fields
+ *
+ * @param model - Model with fields to extract
+ * @param fields - Field names to combine
+ * @param suffix - Optional suffix to append (e.g., "#deleted")
+ * @returns Composite key string (e.g., "@#record#my-alias")
+ * @throws ConfigurationError if a required field is missing
+ */
+function buildCompositeKey(model, fields, suffix) {
+    const parts = fields.map((field) => {
+        const value = model[field];
+        if (value === undefined || value === null) {
+            throw new ConfigurationError(`Missing field for index key: ${field}`);
+        }
+        return String(value);
+    });
+    const key = parts.join(SEPARATOR);
+    return suffix ? key + suffix : key;
+}
+/**
+ * Try to build a composite key, returning undefined if fields are missing
+ *
+ * @param model - Model with fields to extract
+ * @param fields - Field names to combine
+ * @param suffix - Optional suffix to append
+ * @returns Composite key string or undefined if fields missing
+ */
+function tryBuildCompositeKey(model, fields, suffix) {
+    for (const field of fields) {
+        const value = model[field];
+        if (value === undefined || value === null) {
+            return undefined;
+        }
+    }
+    return buildCompositeKey(model, fields, suffix);
+}
+/**
+ * Generate an index name from partition key fields
+ *
+ * @param pk - Partition key field names
+ * @returns Generated index name (e.g., "indexOuModelAlias")
+ */
+function generateIndexName(pk) {
+    const suffix = pk
+        .map((field) => {
+        const str = String(field);
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    })
+        .join("");
+    return `index${suffix}`;
+}
+/**
+ * Calculate the suffix for index keys based on model state
+ *
+ * @param model - Model to check for archived/deleted state
+ * @returns Suffix string (e.g., "", "#archived", "#deleted", "#archived#deleted")
+ */
+function calculateIndexSuffix(model) {
+    let suffix = "";
+    if (model.archivedAt !== undefined && model.archivedAt !== null) {
+        suffix += ARCHIVED_SUFFIX;
+    }
+    if (model.deletedAt !== undefined && model.deletedAt !== null) {
+        suffix += DELETED_SUFFIX;
+    }
+    return suffix;
+}
+/**
+ * Populate index keys on a model based on index definitions
+ *
+ * Only the partition key composite is stored on the model (e.g., indexOu).
+ * The sort key (e.g., sequence) is a regular field that the GSI references directly.
+ *
+ * @param model - Model to populate index keys on
+ * @param indexes - Index definitions to use
+ * @param suffix - Optional suffix to append to all index keys
+ * @returns Model with index keys populated
+ */
+function populateIndexKeys(model, indexes, suffix) {
+    const result = { ...model };
+    const appliedSuffix = suffix ?? calculateIndexSuffix(model);
+    for (const index of indexes) {
+        const indexName = index.name ?? generateIndexName(index.pk);
+        const pkKey = indexName;
+        // For sparse indexes, only populate if all pk fields are present
+        if (index.sparse) {
+            const pkValue = tryBuildCompositeKey(model, index.pk, appliedSuffix);
+            if (pkValue !== undefined) {
+                result[pkKey] = pkValue;
+            }
+        }
+        else {
+            // For non-sparse indexes, always try to populate (will throw if fields missing)
+            const pkValue = tryBuildCompositeKey(model, index.pk, appliedSuffix);
+            if (pkValue !== undefined) {
+                result[pkKey] = pkValue;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Calculate scope from parent reference
+ *
+ * @param parent - Parent model with model and id
+ * @returns Scope string ("{parent.model}#{parent.id}") or APEX ("@") if no parent
+ */
+function calculateScope(parent) {
+    if (!parent) {
+        return "@"; // APEX
+    }
+    return `${parent.model}${SEPARATOR}${parent.id}`;
+}
+
+/**
+ * Model Registry for @jaypie/fabric
+ *
+ * Stores model schemas with their index definitions.
+ * DynamoDB reads from this registry to create GSIs and select indexes for queries.
+ */
+// =============================================================================
+// Registry
+// =============================================================================
+/**
+ * Global model registry - maps model names to their schemas
+ */
+const MODEL_REGISTRY = new Map();
+// =============================================================================
+// Functions
+// =============================================================================
+/**
+ * Register a model schema with its index definitions
+ *
+ * @param schema - Model schema with model name and optional indexes
+ */
+function registerModel(schema) {
+    MODEL_REGISTRY.set(schema.model, schema);
+}
+/**
+ * Get a model schema by name
+ *
+ * @param model - Model name to look up
+ * @returns Model schema or undefined if not registered
+ */
+function getModelSchema(model) {
+    return MODEL_REGISTRY.get(model);
+}
+/**
+ * Get index definitions for a model
+ *
+ * Returns the model's custom indexes if registered,
+ * otherwise returns DEFAULT_INDEXES.
+ *
+ * @param model - Model name to get indexes for
+ * @returns Array of index definitions
+ */
+function getModelIndexes(model) {
+    const schema = MODEL_REGISTRY.get(model);
+    return schema?.indexes ?? DEFAULT_INDEXES;
+}
+/**
+ * Get all registered models
+ *
+ * @returns Array of model names
+ */
+function getRegisteredModels() {
+    return Array.from(MODEL_REGISTRY.keys());
+}
+/**
+ * Get all unique indexes across all registered models
+ *
+ * Used by createTable to collect all GSIs that need to be created.
+ * Deduplicates by index name.
+ *
+ * @returns Array of unique index definitions
+ */
+function getAllRegisteredIndexes() {
+    const indexMap = new Map();
+    // Collect indexes from all registered models
+    for (const schema of MODEL_REGISTRY.values()) {
+        const indexes = schema.indexes ?? [];
+        for (const index of indexes) {
+            const name = index.name ?? generateIndexNameFromPk(index.pk);
+            if (!indexMap.has(name)) {
+                indexMap.set(name, { ...index, name });
+            }
+        }
+    }
+    return Array.from(indexMap.values());
+}
+/**
+ * Check if a model is registered
+ *
+ * @param model - Model name to check
+ * @returns true if model is registered
+ */
+function isModelRegistered(model) {
+    return MODEL_REGISTRY.has(model);
+}
+/**
+ * Clear the model registry (for testing)
+ */
+function clearRegistry() {
+    MODEL_REGISTRY.clear();
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Generate an index name from pk fields (used when index.name is not set)
+ */
+function generateIndexNameFromPk(pk) {
+    const suffix = pk
+        .map((field) => {
+        const str = String(field);
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    })
+        .join("");
+    return `index${suffix}`;
+}
+
+/**
+ * Elementary Field Types
+ *
+ * Defines the 10 elementary field types for the Fabric vocabulary.
+ * Each type has: alias, name, icon, and optional validation/format rules.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/** Elementary type aliases */
+const ELEMENTARY_TYPES = [
+    "boolean",
+    "date",
+    "datetime",
+    "dollars",
+    "multiselect",
+    "number",
+    "reference",
+    "select",
+    "text",
+    "textarea",
+];
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Check if a string is an elementary type
+ */
+function isElementaryType(value) {
+    return (typeof value === "string" &&
+        ELEMENTARY_TYPES.includes(value));
+}
+// =============================================================================
+// Elementary Type Definitions
+// =============================================================================
+/**
+ * Boolean - True/false toggle
+ */
+const BOOLEAN_TYPE = {
+    alias: "boolean",
+    defaultValue: false,
+    description: "True/false toggle",
+    icon: "lucide#toggle-left",
+    inputComponent: "checkbox",
+    name: "Boolean",
+    type: "boolean",
+};
+/**
+ * Date - Date picker (ISO format)
+ */
+const DATE_TYPE = {
+    alias: "date",
+    description: "Date value (YYYY-MM-DD)",
+    formatPattern: "YYYY-MM-DD",
+    icon: "lucide#calendar",
+    inputComponent: "date-picker",
+    name: "Date",
+    type: "date",
+};
+/**
+ * Datetime - Date + time picker
+ */
+const DATETIME_TYPE = {
+    alias: "datetime",
+    description: "Date and time value (ISO 8601)",
+    formatPattern: "YYYY-MM-DDTHH:mm:ssZ",
+    icon: "lucide#calendar-clock",
+    inputComponent: "datetime-picker",
+    name: "Date & Time",
+    type: "datetime",
+};
+/**
+ * Dollars - Currency with formatting
+ */
+const DOLLARS_TYPE = {
+    alias: "dollars",
+    description: "Currency value formatted as $X.XX",
+    formatPattern: "$0,0.00",
+    icon: "lucide#dollar-sign",
+    inputComponent: "currency-input",
+    name: "Dollars",
+    type: "dollars",
+    validation: [
+        { message: "Must be a valid number", type: "numeric" },
+        { message: "Cannot be negative", type: "min", value: 0 },
+    ],
+};
+/**
+ * Multiselect - Multiple selections from options
+ */
+const MULTISELECT_TYPE = {
+    alias: "multiselect",
+    description: "Multiple selections from predefined options",
+    icon: "lucide#list-checks",
+    inputComponent: "multiselect",
+    name: "Multi-Select",
+    options: [], // Populated per-field
+    type: "multiselect",
+};
+/**
+ * Number - Numeric input (integer or float)
+ */
+const NUMBER_TYPE = {
+    alias: "number",
+    description: "Numeric value (integer or decimal)",
+    icon: "lucide#hash",
+    inputComponent: "input[type=number]",
+    name: "Number",
+    type: "number",
+    validation: [{ message: "Must be a valid number", type: "numeric" }],
+};
+/**
+ * Reference - Link to another model
+ */
+const REFERENCE_TYPE = {
+    alias: "reference",
+    description: "Link to another model by id or alias",
+    icon: "lucide#link",
+    inputComponent: "entity-picker",
+    name: "Reference",
+    referenceModel: undefined, // Set per-field
+    type: "reference",
+};
+/**
+ * Select - Single selection from options
+ */
+const SELECT_TYPE = {
+    alias: "select",
+    description: "Single selection from predefined options",
+    icon: "lucide#list",
+    inputComponent: "select",
+    name: "Select",
+    options: [], // Populated per-field
+    type: "select",
+};
+/**
+ * Text - Single-line string input
+ */
+const TEXT_TYPE = {
+    alias: "text",
+    description: "Single-line text input",
+    icon: "lucide#type",
+    inputComponent: "input",
+    name: "Text",
+    type: "text",
+};
+/**
+ * Textarea - Multi-line string input
+ */
+const TEXTAREA_TYPE = {
+    alias: "textarea",
+    description: "Multi-line text input",
+    icon: "lucide#align-left",
+    inputComponent: "textarea",
+    name: "Text Area",
+    type: "textarea",
+};
+// =============================================================================
+// Type Registry
+// =============================================================================
+/**
+ * Registry of all elementary types
+ */
+const ELEMENTARY_TYPE_REGISTRY = {
+    boolean: BOOLEAN_TYPE,
+    date: DATE_TYPE,
+    datetime: DATETIME_TYPE,
+    dollars: DOLLARS_TYPE,
+    multiselect: MULTISELECT_TYPE,
+    number: NUMBER_TYPE,
+    reference: REFERENCE_TYPE,
+    select: SELECT_TYPE,
+    text: TEXT_TYPE,
+    textarea: TEXTAREA_TYPE,
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get an elementary type definition by alias
+ */
+function getElementaryType(alias) {
+    return ELEMENTARY_TYPE_REGISTRY[alias];
+}
+/**
+ * Get all elementary type definitions
+ */
+function getAllElementaryTypes() {
+    return Object.values(ELEMENTARY_TYPE_REGISTRY);
+}
+
+/**
+ * Field Definition - Describes a field's structure and behavior
+ *
+ * Field definitions are the building blocks of model definitions,
+ * specifying type, validation, and metadata for each field.
+ */
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Check if a field ref is an inline definition
+ */
+function isFieldDefinition(ref) {
+    return typeof ref === "object" && "alias" in ref && "type" in ref;
+}
+
+// Service for @jaypie/fabric
+/**
+ * Check if a single-element array is a typed array type constructor.
+ */
+function isTypedArrayConstructor(element) {
+    return (element === Boolean ||
+        element === Number ||
+        element === String ||
+        element === Object ||
+        element === "boolean" ||
+        element === "number" ||
+        element === "string" ||
+        element === "object" ||
+        element === "" ||
+        (typeof element === "object" &&
+            element !== null &&
+            !(element instanceof RegExp) &&
+            Object.keys(element).length === 0));
+}
+/**
+ * Check if a type is a validated string type (array of string literals and/or RegExp).
+ * Distinguishes from typed arrays like [String], [Number], etc.
+ */
+function isValidatedStringType(type) {
+    if (!Array.isArray(type)) {
+        return false;
+    }
+    // Empty array is untyped array, not validated string
+    if (type.length === 0) {
+        return false;
+    }
+    // Single-element arrays with type constructors are typed arrays
+    if (type.length === 1 && isTypedArrayConstructor(type[0])) {
+        return false;
+    }
+    // Check that all elements are strings or RegExp
+    return type.every((item) => typeof item === "string" || item instanceof RegExp);
+}
+/**
+ * Check if a type is a validated number type (array of number literals).
+ * Distinguishes from typed arrays like [Number], etc.
+ */
+function isValidatedNumberType(type) {
+    if (!Array.isArray(type)) {
+        return false;
+    }
+    // Empty array is untyped array, not validated number
+    if (type.length === 0) {
+        return false;
+    }
+    // Single-element arrays with type constructors are typed arrays
+    if (type.length === 1 && isTypedArrayConstructor(type[0])) {
+        return false;
+    }
+    // Check that all elements are numbers
+    return type.every((item) => typeof item === "number");
+}
+/**
+ * Parse input string as JSON if it's a string
+ */
+function parseInput(input) {
+    if (input === undefined || input === null) {
+        return {};
+    }
+    if (typeof input === "string") {
+        if (input === "") {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(input);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                Array.isArray(parsed)) {
+                throw new BadRequestError("Input must be an object");
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error instanceof BadRequestError) {
+                throw error;
+            }
+            throw new BadRequestError("Invalid JSON input");
+        }
+    }
+    if (typeof input === "object" && !Array.isArray(input)) {
+        return input;
+    }
+    throw new BadRequestError("Input must be an object or JSON string");
+}
+/**
+ * Run validation on a value (supports async validators)
+ */
+async function runValidation(value, validate, fieldName) {
+    if (typeof validate === "function") {
+        const result = await validate(value);
+        if (result === false) {
+            throw new BadRequestError(`Validation failed for field "${fieldName}"`);
+        }
+    }
+    else if (validate instanceof RegExp) {
+        if (typeof value !== "string" || !validate.test(value)) {
+            throw new BadRequestError(`Validation failed for field "${fieldName}"`);
+        }
+    }
+    else if (Array.isArray(validate)) {
+        // Check if value matches any item in the array
+        for (const item of validate) {
+            if (item instanceof RegExp) {
+                if (typeof value === "string" && item.test(value)) {
+                    return; // Match found
+                }
+            }
+            else if (typeof item === "function") {
+                try {
+                    const result = await item(value);
+                    if (result !== false) {
+                        return; // Match found
+                    }
+                }
+                catch {
+                    // Continue to next item
+                }
+            }
+            else if (value === item) {
+                return; // Scalar match found
+            }
+        }
+        throw new BadRequestError(`Validation failed for field "${fieldName}"`);
+    }
+}
+/**
+ * Check if a field is required
+ * A field is required unless it has a default OR required is explicitly false
+ */
+function isFieldRequired(definition) {
+    if (definition.required === false) {
+        return false;
+    }
+    if (definition.default !== undefined) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Process a single field through conversion and validation
+ */
+async function processField(fieldName, value, definition) {
+    // Apply default if value is undefined
+    let processedValue = value;
+    if (processedValue === undefined && definition.default !== undefined) {
+        processedValue = definition.default;
+    }
+    // Determine actual type and validation
+    let actualType = definition.type;
+    let validation = definition.validate;
+    // Handle bare RegExp shorthand: /regex/
+    if (definition.type instanceof RegExp) {
+        actualType = String;
+        validation = definition.type; // The RegExp becomes the validation
+    }
+    // Handle validated string shorthand: ["value1", "value2"] or [/regex/]
+    else if (isValidatedStringType(definition.type)) {
+        actualType = String;
+        validation = definition.type; // The array becomes the validation
+    }
+    // Handle validated number shorthand: [1, 2, 3]
+    else if (isValidatedNumberType(definition.type)) {
+        actualType = Number;
+        validation = definition.type; // The array becomes the validation
+    }
+    // Fabric to target type
+    const convertedValue = fabric(processedValue, actualType);
+    // Check if required field is missing
+    if (convertedValue === undefined && isFieldRequired(definition)) {
+        throw new BadRequestError(`Missing required field "${fieldName}"`);
+    }
+    // Run validation if provided
+    if (validation !== undefined && convertedValue !== undefined) {
+        await runValidation(convertedValue, validation, fieldName);
+    }
+    return convertedValue;
+}
+/**
+ * Fabric a service function
+ *
+ * Service builds a function that initiates a "controller" step that:
+ * - Parses the input if it is a string to object
+ * - Fabrics each input field to its type
+ * - Calls the validation function or regular expression or checks the array
+ * - Calls the service function and returns the response
+ *
+ * The returned function has config properties for introspection.
+ */
+function fabricService(config) {
+    const { input: inputDefinitions, service } = config;
+    const handler = async (rawInput, context) => {
+        // Parse input (handles string JSON)
+        const parsedInput = parseInput(rawInput);
+        // If no input definitions, pass through to service or return parsed input
+        if (!inputDefinitions) {
+            if (service) {
+                return service(parsedInput, context);
+            }
+            return parsedInput;
+        }
+        // Process all fields in parallel
+        const entries = Object.entries(inputDefinitions);
+        const processedValues = await Promise.all(entries.map(([fieldName, definition]) => processField(fieldName, parsedInput[fieldName], definition)));
+        // Build processed input object
+        const processedInput = {};
+        entries.forEach(([fieldName], index) => {
+            processedInput[fieldName] = processedValues[index];
+        });
+        // Return processed input if no service, otherwise call service
+        if (service) {
+            return service(processedInput, context);
+        }
+        return processedInput;
+    };
+    // Attach config properties directly to handler for flat access
+    const typedHandler = handler;
+    typedHandler.$fabric = FABRIC_VERSION;
+    if (config.alias !== undefined)
+        typedHandler.alias = config.alias;
+    if (config.description !== undefined)
+        typedHandler.description = config.description;
+    if (config.input !== undefined)
+        typedHandler.input = config.input;
+    if (config.service !== undefined)
+        typedHandler.service = config.service;
+    return typedHandler;
+}
+
+// Resolve inline service definitions to full Service objects
+/**
+ * Type guard to check if a value is a pre-instantiated Service
+ * A Service is a function with the `$fabric` property set by fabricService
+ */
+function isService(value) {
+    return typeof value === "function" && "$fabric" in value;
+}
+/**
+ * Resolve a service configuration to a full Service object
+ *
+ * Supports two patterns:
+ * 1. Inline service definition - pass a plain function as `service` along with
+ *    `alias`, `description`, and `input` in the config
+ * 2. Pre-instantiated Service - pass a Service object as `service`
+ *
+ * When a pre-instantiated Service is passed, config fields act as overrides:
+ * - `alias` overrides service.alias
+ * - `description` overrides service.description
+ * - `input` overrides service.input
+ *
+ * The original Service is never mutated - a new Service is created when overrides
+ * are applied.
+ *
+ * @example
+ * ```typescript
+ * // Inline service definition
+ * const service = resolveService({
+ *   alias: "greet",
+ *   description: "Greet a user",
+ *   input: { name: { type: String } },
+ *   service: ({ name }) => `Hello, ${name}!`,
+ * });
+ *
+ * // Pre-instantiated with override
+ * const baseService = fabricService({ alias: "foo", service: (x) => x });
+ * const overridden = resolveService({
+ *   alias: "bar",  // Override alias
+ *   service: baseService,
+ * });
+ * ```
+ */
+function resolveService(config) {
+    const { alias, description, input, service } = config;
+    if (isService(service)) {
+        // Service is pre-instantiated - config fields act as overrides
+        // Create new Service with merged properties (config overrides service)
+        return fabricService({
+            alias: alias ?? service.alias,
+            description: description ?? service.description,
+            input: input ?? service.input,
+            service: service.service,
+        });
+    }
+    // Service is an inline function - create Service from config
+    return fabricService({
+        alias,
+        description,
+        input,
+        service,
+    });
+}
+
+/**
+ * Status Type for @jaypie/fabric
+ *
+ * Standard status values for fields that track processing state.
+ */
+/**
+ * Valid status values for status fields
+ */
+const STATUS_VALUES = [
+    "canceled",
+    "complete",
+    "error",
+    "pending",
+    "processing",
+    "queued",
+    "sending",
+];
+/**
+ * Status type for use in createService input definitions
+ *
+ * Usage:
+ * ```typescript
+ * const handler = createService({
+ *   input: {
+ *     status: { type: StatusType, description: "Current status" },
+ *   },
+ * });
+ * ```
+ */
+const StatusType = [...STATUS_VALUES];
+/**
+ * Check if a value is a valid status
+ */
+function isStatus(value) {
+    return (typeof value === "string" &&
+        STATUS_VALUES.includes(value));
+}
+
+export { APEX, ARCHIVED_SUFFIX, BOOLEAN_TYPE, DATETIME_TYPE, DATE_TYPE, DEFAULT_INDEXES, DEFAULT_SORT_KEY, DELETED_SUFFIX, DOLLARS_TYPE, DateType, ELEMENTARY_TYPES, ELEMENTARY_TYPE_REGISTRY, FABRIC_MODEL_AUTO_FIELDS, FABRIC_MODEL_FIELDS, FABRIC_MODEL_REQUIRED_FIELDS, FABRIC_MODEL_TIMESTAMP_FIELDS, FABRIC_VERSION, MULTISELECT_TYPE, NUMBER_TYPE, REFERENCE_TYPE, SELECT_TYPE, SEPARATOR, STATUS_VALUES, SYSTEM_MODELS, StatusType, TEXTAREA_TYPE, TEXT_TYPE, buildCompositeKey, calculateIndexSuffix, calculateScope, clearRegistry, computeResolvedName, createFabricModelInput, fabric, fabricArray, fabricBoolean, fabricDate, fabricNumber, fabricObject, fabricService, fabricString, generateIndexName, getAllElementaryTypes, getAllRegisteredIndexes, getElementaryType, getModelIndexes, getModelSchema, getRegisteredModels, hasFabricModelShape, isAutoField, isDateType, isElementaryType, isFabricModel, isFieldDefinition, isModelRegistered, isStatus, isTimestampField, isValidDate, pickFabricModelFields, populateIndexKeys, registerModel, resolveFromArray, resolveFromDate, resolveFromObject, resolveService, resolveWithFallback, tryBuildCompositeKey };
+//# sourceMappingURL=index.js.map