@jaypie/dynamodb 0.1.2 → 0.2.0

package/dist/esm/index.d.ts

@@ -1,6 +1,10 @@
 export { getDocClient, getTableName, initClient, isInitialized, resetClient, } from "./client.js";
 export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, INDEX_ALIAS, INDEX_CLASS, INDEX_OU, INDEX_TYPE, INDEX_XID, SEPARATOR, } from "./constants.js";
 export { archiveEntity, deleteEntity, destroyEntity, getEntity, putEntity, updateEntity, } from "./entities.js";
-export { buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, indexEntity, } from "./keyBuilders.js";
+export { buildCompositeKey, buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, DEFAULT_INDEXES, indexEntity, } from "./keyBuilders.js";
 export { queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, } from "./queries.js";
-export type { BaseQueryOptions, DynamoClientConfig, FabricEntity, ParentReference, QueryResult, } from "./types.js";
+export { query } from "./query.js";
+export type { QueryParams } from "./query.js";
+export { exportEntities, exportEntitiesToJson, seedEntities, seedEntityIfNotExists, } from "./seedExport.js";
+export type { BaseQueryOptions, DynamoClientConfig, ParentReference, QueryResult, StorableEntity, } from "./types.js";
+export type { ExportResult, SeedOptions, SeedResult } from "./seedExport.js";

package/dist/esm/index.js

@@ -1,7 +1,8 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
 import { ConfigurationError } from '@jaypie/errors';
-import { serviceHandler } from '@jaypie/vocabulary';
+import { getModelIndexes, populateIndexKeys, SEPARATOR, buildCompositeKey as buildCompositeKey$1, APEX, calculateOu as calculateOu$1, serviceHandler, ARCHIVED_SUFFIX, DELETED_SUFFIX } from '@jaypie/vocabulary';
+export { APEX, ARCHIVED_SUFFIX, DEFAULT_INDEXES, DELETED_SUFFIX, SEPARATOR } from '@jaypie/vocabulary';
 
 // Environment variable names
 const ENV_AWS_REGION = "AWS_REGION";
@@ -81,19 +82,17 @@ function resetClient() {
     tableName = null;
 }
 
-// Primary markers
-const APEX = "@"; // Root-level marker (DynamoDB prohibits empty strings)
-const SEPARATOR = "#"; // Composite key separator
-// GSI names
+// Re-export shared constants from vocabulary
+// GSI names (derived from DEFAULT_INDEXES)
 const INDEX_ALIAS = "indexAlias";
 const INDEX_CLASS = "indexClass";
 const INDEX_OU = "indexOu";
 const INDEX_TYPE = "indexType";
 const INDEX_XID = "indexXid";
-// Index suffixes for soft state
-const ARCHIVED_SUFFIX = "#archived";
-const DELETED_SUFFIX = "#deleted";
 
+// =============================================================================
+// Key Builders
+// =============================================================================
 /**
  * Build the indexOu key for hierarchical queries
  * @param ou - The organizational unit (APEX or "{parent.model}#{parent.id}")
@@ -143,6 +142,20 @@ function buildIndexType(ou, model, type) {
 function buildIndexXid(ou, model, xid) {
     return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
 }
+// =============================================================================
+// New Vocabulary-Based Functions
+// =============================================================================
+/**
+ * Build a composite key from entity fields
+ *
+ * @param entity - Entity with fields to extract
+ * @param fields - Field names to combine with SEPARATOR
+ * @param suffix - Optional suffix to append (e.g., "#deleted")
+ * @returns Composite key string
+ */
+function buildCompositeKey(entity, fields, suffix) {
+    return buildCompositeKey$1(entity, fields, suffix);
+}
 /**
  * Calculate the organizational unit from a parent reference
  * @param parent - Optional parent entity reference
@@ -152,10 +165,14 @@ function calculateOu(parent) {
     if (!parent) {
         return APEX;
     }
-    return `${parent.model}${SEPARATOR}${parent.id}`;
+    return calculateOu$1(parent);
 }
 /**
  * Auto-populate GSI index keys on an entity
+ *
+ * Uses the model's registered indexes (from vocabulary registry) or
+ * DEFAULT_INDEXES if no custom indexes are registered.
+ *
  * - indexOu is always populated from ou + model
  * - indexAlias is populated only when alias is present
  * - indexClass is populated only when class is present
@@ -167,27 +184,9 @@ function calculateOu(parent) {
  * @returns The entity with populated index keys
  */
 function indexEntity(entity, suffix = "") {
-    const result = { ...entity };
-    // indexOu is always set (from ou + model)
-    result.indexOu = buildIndexOu(entity.ou, entity.model) + suffix;
-    // Optional indexes - only set when the source field is present
-    if (entity.alias !== undefined) {
-        result.indexAlias =
-            buildIndexAlias(entity.ou, entity.model, entity.alias) + suffix;
-    }
-    if (entity.class !== undefined) {
-        result.indexClass =
-            buildIndexClass(entity.ou, entity.model, entity.class) + suffix;
-    }
-    if (entity.type !== undefined) {
-        result.indexType =
-            buildIndexType(entity.ou, entity.model, entity.type) + suffix;
-    }
-    if (entity.xid !== undefined) {
-        result.indexXid =
-            buildIndexXid(entity.ou, entity.model, entity.xid) + suffix;
-    }
-    return result;
+    const indexes = getModelIndexes(entity.model);
+    // Cast through unknown to bridge the type gap between StorableEntity and IndexableEntity
+    return populateIndexKeys(entity, indexes, suffix);
 }
 
 /**
@@ -233,7 +232,7 @@ const getEntity = serviceHandler({
  * Auto-populates GSI index keys via indexEntity
  *
  * Note: This is a regular async function (not serviceHandler) because it accepts
- * complex FabricEntity objects that can't be coerced by vocabulary's type system.
+ * complex StorableEntity objects that can't be coerced by vocabulary's type system.
  */
 async function putEntity({ entity, }) {
     const docClient = getDocClient();
@@ -252,7 +251,7 @@ async function putEntity({ entity, }) {
  * Auto-populates GSI index keys and sets updatedAt
  *
  * Note: This is a regular async function (not serviceHandler) because it accepts
- * complex FabricEntity objects that can't be coerced by vocabulary's type system.
+ * complex StorableEntity objects that can't be coerced by vocabulary's type system.
  */
 async function updateEntity({ entity, }) {
     const docClient = getDocClient();
@@ -370,7 +369,7 @@ const destroyEntity = serviceHandler({
  * Calculate the suffix based on archived/deleted flags
  * When both are true, returns combined suffix (archived first, alphabetically)
  */
-function calculateSuffix({ archived, deleted, }) {
+function calculateSuffix$1({ archived, deleted, }) {
     if (archived && deleted) {
         return ARCHIVED_SUFFIX + DELETED_SUFFIX;
     }
@@ -417,7 +416,7 @@ async function executeQuery(indexName, keyValue, options = {}) {
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
 async function queryByOu({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, }) {
-    const suffix = calculateSuffix({ archived, deleted });
+    const suffix = calculateSuffix$1({ archived, deleted });
     const keyValue = buildIndexOu(ou, model) + suffix;
     return executeQuery(INDEX_OU, keyValue, {
         ascending,
@@ -455,7 +454,7 @@ const queryByAlias = serviceHandler({
         const deletedBool = deleted;
         const modelStr = model;
         const ouStr = ou;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
+        const suffix = calculateSuffix$1({ archived: archivedBool, deleted: deletedBool });
         const keyValue = buildIndexAlias(ouStr, modelStr, aliasStr) + suffix;
         const result = await executeQuery(INDEX_ALIAS, keyValue, {
             limit: 1,
@@ -471,7 +470,7 @@ const queryByAlias = serviceHandler({
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
 async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, ou, recordClass, startKey, }) {
-    const suffix = calculateSuffix({ archived, deleted });
+    const suffix = calculateSuffix$1({ archived, deleted });
     const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
     return executeQuery(INDEX_CLASS, keyValue, {
         ascending,
@@ -487,7 +486,7 @@ async function queryByClass({ archived = false, ascending = false, deleted = fal
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
 async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, type, }) {
-    const suffix = calculateSuffix({ archived, deleted });
+    const suffix = calculateSuffix$1({ archived, deleted });
     const keyValue = buildIndexType(ou, model, type) + suffix;
     return executeQuery(INDEX_TYPE, keyValue, {
         ascending,
@@ -525,7 +524,7 @@ const queryByXid = serviceHandler({
         const modelStr = model;
         const ouStr = ou;
         const xidStr = xid;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
+        const suffix = calculateSuffix$1({ archived: archivedBool, deleted: deletedBool });
         const keyValue = buildIndexXid(ouStr, modelStr, xidStr) + suffix;
         const result = await executeQuery(INDEX_XID, keyValue, {
             limit: 1,
@@ -534,5 +533,320 @@ const queryByXid = serviceHandler({
     },
 });
 
-export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, INDEX_ALIAS, INDEX_CLASS, INDEX_OU, INDEX_TYPE, INDEX_XID, SEPARATOR, archiveEntity, buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, deleteEntity, destroyEntity, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, putEntity, queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, resetClient, updateEntity };
+/**
+ * Unified Query Function with Auto-Detect Index Selection
+ *
+ * The query() function automatically selects the best index based on
+ * the filter fields provided. This simplifies query construction by
+ * removing the need to know which specific GSI to use.
+ */
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Calculate the suffix based on archived/deleted flags
+ */
+function calculateSuffix(archived, deleted) {
+    if (archived && deleted) {
+        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+    }
+    if (archived) {
+        return ARCHIVED_SUFFIX;
+    }
+    if (deleted) {
+        return DELETED_SUFFIX;
+    }
+    return "";
+}
+/**
+ * Build a combined filter object from params
+ */
+function buildFilterObject(params) {
+    const result = {
+        model: params.model,
+    };
+    if (params.ou !== undefined) {
+        result.ou = params.ou;
+    }
+    if (params.filter) {
+        Object.assign(result, params.filter);
+    }
+    return result;
+}
+/**
+ * Score an index based on how well it matches the filter fields
+ */
+function scoreIndex(index, filterFields) {
+    let matchedFields = 0;
+    let pkComplete = true;
+    for (const field of index.pk) {
+        if (filterFields[field] !== undefined) {
+            matchedFields++;
+        }
+        else {
+            pkComplete = false;
+        }
+    }
+    return {
+        index,
+        matchedFields,
+        pkComplete,
+    };
+}
+/**
+ * Select the best index for the given filter
+ *
+ * Scoring criteria:
+ * 1. Index must have all pk fields present (pkComplete)
+ * 2. Prefer indexes with more matched fields
+ * 3. Prefer more specific indexes (more pk fields)
+ */
+function selectBestIndex(indexes, filterFields) {
+    const scores = indexes.map((index) => scoreIndex(index, filterFields));
+    // Filter to only complete matches
+    const completeMatches = scores.filter((s) => s.pkComplete);
+    if (completeMatches.length === 0) {
+        const availableIndexes = indexes
+            .map((i) => i.name ?? `[${i.pk.join(", ")}]`)
+            .join(", ");
+        const providedFields = Object.keys(filterFields).join(", ");
+        throw new ConfigurationError(`No index matches filter fields. ` +
+            `Provided: ${providedFields}. ` +
+            `Available indexes: ${availableIndexes}`);
+    }
+    // Sort by:
+    // 1. More matched fields first (descending)
+    // 2. More pk fields (more specific) first (descending)
+    completeMatches.sort((a, b) => {
+        const fieldDiff = b.matchedFields - a.matchedFields;
+        if (fieldDiff !== 0)
+            return fieldDiff;
+        return b.index.pk.length - a.index.pk.length;
+    });
+    return completeMatches[0].index;
+}
+// =============================================================================
+// Main Query Function
+// =============================================================================
+/**
+ * Query entities with automatic index selection
+ *
+ * The query function automatically selects the best GSI based on
+ * the filter fields provided. This removes the need to know which
+ * specific query function (queryByOu, queryByAlias, etc.) to use.
+ *
+ * @example
+ * // Uses indexOu (pk: ["ou", "model"])
+ * const allMessages = await query({ model: "message", ou: `chat#${chatId}` });
+ *
+ * @example
+ * // Uses indexAlias (pk: ["ou", "model", "alias"])
+ * const byAlias = await query({
+ *   model: "record",
+ *   ou: "@",
+ *   filter: { alias: "my-record" },
+ * });
+ *
+ * @example
+ * // Uses a custom registered index if model has one
+ * const byChat = await query({
+ *   model: "message",
+ *   filter: { chatId: "abc-123" },
+ * });
+ */
+async function query(params) {
+    const { archived = false, ascending = false, deleted = false, limit, model, startKey, } = params;
+    // Build the combined filter object
+    const filterFields = buildFilterObject(params);
+    // Get indexes for this model (custom or DEFAULT_INDEXES)
+    const indexes = getModelIndexes(model);
+    // Select the best matching index
+    const selectedIndex = selectBestIndex(indexes, filterFields);
+    const indexName = selectedIndex.name ?? generateIndexName(selectedIndex.pk);
+    // Build the partition key value
+    const suffix = calculateSuffix(archived, deleted);
+    const keyValue = buildCompositeKey(filterFields, selectedIndex.pk, suffix);
+    // Execute the query
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    const command = new QueryCommand({
+        ExclusiveStartKey: startKey,
+        ExpressionAttributeNames: {
+            "#pk": indexName,
+        },
+        ExpressionAttributeValues: {
+            ":pkValue": keyValue,
+        },
+        IndexName: indexName,
+        KeyConditionExpression: "#pk = :pkValue",
+        ...(limit && { Limit: limit }),
+        ScanIndexForward: ascending,
+        TableName: tableName,
+    });
+    const response = await docClient.send(command);
+    return {
+        items: (response.Items ?? []),
+        lastEvaluatedKey: response.LastEvaluatedKey,
+    };
+}
+/**
+ * Generate an index name from pk fields
+ */
+function generateIndexName(pk) {
+    const suffix = pk
+        .map((field) => field.charAt(0).toUpperCase() + field.slice(1))
+        .join("");
+    return `index${suffix}`;
+}
+
+/**
+ * Seed a single entity if it doesn't already exist
+ *
+ * @param entity - Partial entity with at least alias, model, and ou
+ * @returns true if entity was created, false if it already exists
+ */
+async function seedEntityIfNotExists(entity) {
+    if (!entity.alias || !entity.model || !entity.ou) {
+        throw new Error("Entity must have alias, model, and ou to check existence");
+    }
+    // Check if entity already exists
+    const existing = await queryByAlias({
+        alias: entity.alias,
+        model: entity.model,
+        ou: entity.ou,
+    });
+    if (existing) {
+        return false;
+    }
+    // Generate required fields if missing
+    const now = new Date().toISOString();
+    const completeEntity = {
+        createdAt: entity.createdAt ?? now,
+        id: entity.id ?? crypto.randomUUID(),
+        model: entity.model,
+        name: entity.name ?? entity.alias,
+        ou: entity.ou,
+        sequence: entity.sequence ?? Date.now(),
+        updatedAt: entity.updatedAt ?? now,
+        ...entity,
+    };
+    await putEntity({ entity: completeEntity });
+    return true;
+}
+/**
+ * Seed multiple entities (idempotent)
+ *
+ * - Checks existence by alias (via queryByAlias) before creating
+ * - Auto-generates id (UUID), createdAt, updatedAt if missing
+ * - Skip existing unless replace: true
+ * - Returns counts of created/skipped/errors
+ *
+ * @param entities - Array of partial entities to seed
+ * @param options - Seed options
+ * @returns Result with created, skipped, and errors arrays
+ */
+async function seedEntities(entities, options = {}) {
+    const { dryRun = false, replace = false } = options;
+    const result = {
+        created: [],
+        errors: [],
+        skipped: [],
+    };
+    for (const entity of entities) {
+        const alias = entity.alias ?? entity.name ?? "unknown";
+        try {
+            if (!entity.model || !entity.ou) {
+                throw new Error("Entity must have model and ou");
+            }
+            // For entities with alias, check existence
+            if (entity.alias) {
+                const existing = await queryByAlias({
+                    alias: entity.alias,
+                    model: entity.model,
+                    ou: entity.ou,
+                });
+                if (existing && !replace) {
+                    result.skipped.push(alias);
+                    continue;
+                }
+                // If replacing, use existing ID to update rather than create new
+                if (existing && replace) {
+                    entity.id = existing.id;
+                }
+            }
+            if (dryRun) {
+                result.created.push(alias);
+                continue;
+            }
+            // Generate required fields if missing
+            const now = new Date().toISOString();
+            const completeEntity = {
+                createdAt: entity.createdAt ?? now,
+                id: entity.id ?? crypto.randomUUID(),
+                model: entity.model,
+                name: entity.name ?? entity.alias ?? "Unnamed",
+                ou: entity.ou,
+                sequence: entity.sequence ?? Date.now(),
+                updatedAt: entity.updatedAt ?? now,
+                ...entity,
+            };
+            await putEntity({ entity: completeEntity });
+            result.created.push(alias);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push({ alias, error: errorMessage });
+        }
+    }
+    return result;
+}
+/**
+ * Export entities by model and organizational unit
+ *
+ * - Paginates through all matching entities via queryByOu
+ * - Returns entities sorted by sequence (ascending)
+ *
+ * @param model - The entity model name
+ * @param ou - The organizational unit
+ * @param limit - Optional maximum number of entities to export
+ * @returns Export result with entities and count
+ */
+async function exportEntities(model, ou, limit) {
+    const entities = [];
+    let startKey;
+    let remaining = limit;
+    do {
+        const batchLimit = remaining !== undefined ? Math.min(remaining, 100) : undefined;
+        const { items, lastEvaluatedKey } = await queryByOu({
+            ascending: true,
+            limit: batchLimit,
+            model,
+            ou,
+            startKey,
+        });
+        entities.push(...items);
+        startKey = lastEvaluatedKey;
+        if (remaining !== undefined) {
+            remaining -= items.length;
+        }
+    } while (startKey && (remaining === undefined || remaining > 0));
+    return {
+        count: entities.length,
+        entities,
+    };
+}
+/**
+ * Export entities as a JSON string
+ *
+ * @param model - The entity model name
+ * @param ou - The organizational unit
+ * @param pretty - Format JSON with indentation (default: true)
+ * @returns JSON string of exported entities
+ */
+async function exportEntitiesToJson(model, ou, pretty = true) {
+    const { entities } = await exportEntities(model, ou);
+    return pretty ? JSON.stringify(entities, null, 2) : JSON.stringify(entities);
+}
+
+export { INDEX_ALIAS, INDEX_CLASS, INDEX_OU, INDEX_TYPE, INDEX_XID, archiveEntity, buildCompositeKey, buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, deleteEntity, destroyEntity, exportEntities, exportEntitiesToJson, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, putEntity, query, queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, resetClient, seedEntities, seedEntityIfNotExists, updateEntity };
 //# sourceMappingURL=index.js.map