@jaypie/dynamodb 0.4.3 → 0.5.0

package/dist/esm/mcp/index.js

@@ -1,5 +1,5 @@
 import { fabricMcp } from '@jaypie/fabric/mcp';
-import { getModelIndexes, populateIndexKeys, SEPARATOR, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX, getAllRegisteredIndexes } from '@jaypie/fabric';
+import { getModelIndexes, populateIndexKeys, buildCompositeKey as buildCompositeKey$1, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX, getGsiAttributeNames, SEPARATOR, getAllRegisteredIndexes } from '@jaypie/fabric';
 import { DynamoDBClient, DescribeTableCommand, CreateTableCommand } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
 import { ConfigurationError } from '@jaypie/errors';
@@ -75,85 +75,45 @@ function isInitialized() {
     return docClient !== null && tableName !== null;
 }
 
-// Re-export shared constants from fabric
-// GSI names
-const INDEX_ALIAS = "indexAlias";
-const INDEX_CATEGORY = "indexCategory";
-const INDEX_SCOPE = "indexScope";
-const INDEX_TYPE = "indexType";
-const INDEX_XID = "indexXid";
-
 // =============================================================================
 // Key Builders
 // =============================================================================
 /**
- * Build the indexScope key for hierarchical queries
- * @param scope - The scope (APEX or "{parent.model}#{parent.id}")
- * @param model - The entity model name
- * @returns Composite key: "{scope}#{model}"
- */
-function buildIndexScope(scope, model) {
-    return `${scope}${SEPARATOR}${model}`;
-}
-/**
- * Build the indexAlias key for human-friendly lookups
- * @param scope - The scope
- * @param model - The entity model name
- * @param alias - The human-friendly alias
- * @returns Composite key: "{scope}#{model}#{alias}"
- */
-function buildIndexAlias(scope, model, alias) {
-    return `${scope}${SEPARATOR}${model}${SEPARATOR}${alias}`;
-}
-/**
- * Build the indexCategory key for category filtering
- * @param scope - The scope
- * @param model - The entity model name
- * @param category - The category classification
- * @returns Composite key: "{scope}#{model}#{category}"
- */
-function buildIndexCategory(scope, model, category) {
-    return `${scope}${SEPARATOR}${model}${SEPARATOR}${category}`;
-}
-/**
- * Build the indexType key for type filtering
- * @param scope - The scope
- * @param model - The entity model name
- * @param type - The type classification
- * @returns Composite key: "{scope}#{model}#{type}"
- */
-function buildIndexType(scope, model, type) {
-    return `${scope}${SEPARATOR}${model}${SEPARATOR}${type}`;
-}
-/**
- * Build the indexXid key for external ID lookups
- * @param scope - The scope
- * @param model - The entity model name
- * @param xid - The external ID
- * @returns Composite key: "{scope}#{model}#{xid}"
+ * 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 buildIndexXid(scope, model, xid) {
-    return `${scope}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+function buildCompositeKey(entity, fields, suffix) {
+    return buildCompositeKey$1(entity, fields, suffix);
 }
 /**
- * Auto-populate GSI index keys on an entity
+ * Auto-populate GSI index keys on an entity and advance its write timestamps.
  *
- * Uses the model's registered indexes (from the fabric registry).
+ * - Bumps `updatedAt` to now on every call.
+ * - Backfills `createdAt` to the same now if not already set.
+ * - Populates GSI attributes (pk composite and sk composite when applicable)
+ *   using the indexes registered for the entity's model.
  *
- * - indexScope is always populated from scope + model
- * - indexAlias is populated only when alias is present
- * - indexCategory is populated only when category is present
- * - indexType is populated only when type is present
- * - indexXid is populated only when xid is present
+ * Callers (putEntity, updateEntity, deleteEntity, archiveEntity,
+ * transactWriteEntities) go through this one function so `updatedAt` is
+ * always fresh and never forgotten.
  *
- * @param entity - The entity to populate index keys for
- * @param suffix - Optional suffix to append to all index keys (e.g., "#deleted", "#archived")
- * @returns The entity with populated index keys
+ * @param entity - The entity to index
+ * @param suffix - Optional suffix override (defaults to archived/deleted state)
+ * @returns A new entity with timestamps bumped and index keys populated
  */
-function indexEntity(entity, suffix = "") {
+function indexEntity(entity, suffix) {
+    const now = new Date().toISOString();
+    const bumped = {
+        ...entity,
+        createdAt: entity.createdAt ?? now,
+        updatedAt: now,
+    };
     const indexes = getModelIndexes(entity.model);
-    // Cast through unknown to bridge the type gap between StorableEntity and IndexableModel
-    return populateIndexKeys(entity, indexes, suffix);
+    return populateIndexKeys(bumped, indexes, suffix);
 }
 
 /**
@@ -174,20 +134,19 @@ function calculateEntitySuffix(entity) {
     return "";
 }
 /**
- * Get a single entity by primary key
+ * Get a single entity by primary key (id)
  */
 const getEntity = fabricService({
     alias: "getEntity",
-    description: "Get a single entity by primary key",
+    description: "Get a single entity by id",
     input: {
-        id: { type: String, description: "Entity ID (sort key)" },
-        model: { type: String, description: "Entity model (partition key)" },
+        id: { type: String, description: "Entity id (partition key)" },
     },
-    service: async ({ id, model }) => {
+    service: async ({ id }) => {
         const docClient = getDocClient();
         const tableName = getTableName();
         const command = new GetCommand({
-            Key: { id, model },
+            Key: { id },
             TableName: tableName,
         });
         const response = await docClient.send(command);
@@ -195,16 +154,12 @@ const getEntity = fabricService({
     },
 });
 /**
- * Put (create or replace) an entity
- * Auto-populates GSI index keys via indexEntity
- *
- * Note: This is a regular async function (not fabricService) because it accepts
- * complex StorableEntity objects that can't be coerced by vocabulary's type system.
+ * Put (create or replace) an entity.
+ * `indexEntity` auto-bumps `updatedAt` and backfills `createdAt`.
  */
 async function putEntity({ entity, }) {
     const docClient = getDocClient();
     const tableName = getTableName();
-    // Auto-populate index keys
     const indexedEntity = indexEntity(entity);
     const command = new PutCommand({
         Item: indexedEntity,
@@ -214,20 +169,13 @@ async function putEntity({ entity, }) {
     return indexedEntity;
 }
 /**
- * Update an existing entity
- * Auto-populates GSI index keys and sets updatedAt
- *
- * Note: This is a regular async function (not fabricService) because it accepts
- * complex StorableEntity objects that can't be coerced by vocabulary's type system.
+ * Update an existing entity.
+ * `indexEntity` auto-bumps `updatedAt` — callers never set it manually.
  */
 async function updateEntity({ entity, }) {
     const docClient = getDocClient();
     const tableName = getTableName();
-    // Update timestamp and re-index
-    const updatedEntity = indexEntity({
-        ...entity,
-        updatedAt: new Date().toISOString(),
-    });
+    const updatedEntity = indexEntity(entity);
     const command = new PutCommand({
         Item: updatedEntity,
         TableName: tableName,
@@ -243,25 +191,21 @@ const deleteEntity = fabricService({
     alias: "deleteEntity",
     description: "Soft delete an entity (sets deletedAt timestamp)",
     input: {
-        id: { type: String, description: "Entity ID (sort key)" },
-        model: { type: String, description: "Entity model (partition key)" },
+        id: { type: String, description: "Entity id" },
     },
-    service: async ({ id, model }) => {
+    service: async ({ id }) => {
         const docClient = getDocClient();
         const tableName = getTableName();
-        // Fetch the current entity
-        const existing = await getEntity({ id, model });
+        const existing = await getEntity({ id });
         if (!existing) {
             return false;
         }
         const now = new Date().toISOString();
-        // Build updated entity with deletedAt
+        // indexEntity will bump updatedAt again; set deletedAt here.
         const updatedEntity = {
             ...existing,
             deletedAt: now,
-            updatedAt: now,
         };
-        // Calculate suffix based on combined state (may already be archived)
         const suffix = calculateEntitySuffix(updatedEntity);
         const deletedEntity = indexEntity(updatedEntity, suffix);
         const command = new PutCommand({
@@ -280,25 +224,20 @@ const archiveEntity = fabricService({
     alias: "archiveEntity",
     description: "Archive an entity (sets archivedAt timestamp)",
     input: {
-        id: { type: String, description: "Entity ID (sort key)" },
-        model: { type: String, description: "Entity model (partition key)" },
+        id: { type: String, description: "Entity id" },
     },
-    service: async ({ id, model }) => {
+    service: async ({ id }) => {
         const docClient = getDocClient();
         const tableName = getTableName();
-        // Fetch the current entity
-        const existing = await getEntity({ id, model });
+        const existing = await getEntity({ id });
         if (!existing) {
             return false;
         }
         const now = new Date().toISOString();
-        // Build updated entity with archivedAt
         const updatedEntity = {
             ...existing,
             archivedAt: now,
-            updatedAt: now,
         };
-        // Calculate suffix based on combined state (may already be deleted)
         const suffix = calculateEntitySuffix(updatedEntity);
         const archivedEntity = indexEntity(updatedEntity, suffix);
         const command = new PutCommand({
@@ -317,14 +256,13 @@ const destroyEntity = fabricService({
     alias: "destroyEntity",
     description: "Hard delete an entity (permanently removes from table)",
     input: {
-        id: { type: String, description: "Entity ID (sort key)" },
-        model: { type: String, description: "Entity model (partition key)" },
+        id: { type: String, description: "Entity id" },
     },
-    service: async ({ id, model }) => {
+    service: async ({ id }) => {
         const docClient = getDocClient();
         const tableName = getTableName();
         const command = new DeleteCommand({
-            Key: { id, model },
+            Key: { id },
             TableName: tableName,
         });
         await docClient.send(command);
@@ -332,9 +270,13 @@ const destroyEntity = fabricService({
     },
 });
 
+// =============================================================================
+// Helpers
+// =============================================================================
 /**
- * Calculate the suffix based on archived/deleted flags
- * When both are true, returns combined suffix (archived first, alphabetically)
+ * Calculate the suffix for the GSI partition key based on archived/deleted
+ * flags. Suffix stays on pk so deleted/archived entities are queried as their
+ * own partition (active queries skip them naturally).
  */
 function calculateSuffix({ archived, deleted, }) {
     if (archived && deleted) {
@@ -349,22 +291,51 @@ function calculateSuffix({ archived, deleted, }) {
     return "";
 }
 /**
- * Execute a GSI query with common options
+ * Find the registered index for a model that matches a given partition-key
+ * shape. The matching index is the first one whose pk equals the expected
+ * fields. Throws ConfigurationError if no match is found.
+ */
+function requireIndex(model, pkFields) {
+    const indexes = getModelIndexes(model);
+    const match = indexes.find((index) => index.pk.length === pkFields.length &&
+        index.pk.every((field, i) => field === pkFields[i]));
+    if (!match) {
+        throw new ConfigurationError(`Model "${model}" has no index with pk=[${pkFields.join(", ")}]. ` +
+            `Register one with fabricIndex(${pkFields.length > 1 ? `"${pkFields[1]}"` : ""}).`);
+    }
+    return match;
+}
+/**
+ * Execute a GSI query.
+ *
+ * - pk: exact match on the index partition key
+ * - skPrefix: optional begins_with on the index sort key (used when the index
+ *   has a composite sk like [scope, updatedAt])
  */
-async function executeQuery(indexName, keyValue, options = {}) {
-    const { ascending = false, limit, startKey } = options;
+async function executeQuery(index, pkValue, options = {}) {
+    const { ascending = false, limit, skPrefix, startKey } = options;
+    const attrs = getGsiAttributeNames(index);
+    const indexName = attrs.pk;
+    const expressionAttributeNames = {
+        "#pk": indexName,
+    };
+    const expressionAttributeValues = {
+        ":pkValue": pkValue,
+    };
+    let keyConditionExpression = "#pk = :pkValue";
+    if (skPrefix !== undefined && attrs.sk) {
+        expressionAttributeNames["#sk"] = attrs.sk;
+        expressionAttributeValues[":skPrefix"] = skPrefix;
+        keyConditionExpression += " AND begins_with(#sk, :skPrefix)";
+    }
     const docClient = getDocClient();
     const tableName = getTableName();
     const command = new QueryCommand({
         ExclusiveStartKey: startKey,
-        ExpressionAttributeNames: {
-            "#pk": indexName,
-        },
-        ExpressionAttributeValues: {
-            ":pkValue": keyValue,
-        },
+        ExpressionAttributeNames: expressionAttributeNames,
+        ExpressionAttributeValues: expressionAttributeValues,
         IndexName: indexName,
-        KeyConditionExpression: "#pk = :pkValue",
+        KeyConditionExpression: keyConditionExpression,
         ...(limit && { Limit: limit }),
         ScanIndexForward: ascending,
         TableName: tableName,
@@ -375,25 +346,30 @@ async function executeQuery(indexName, keyValue, options = {}) {
         lastEvaluatedKey: response.LastEvaluatedKey,
     };
 }
+function scopePrefix(scope) {
+    return scope === undefined ? undefined : `${scope}${SEPARATOR}`;
+}
+// =============================================================================
+// Query Functions
+// =============================================================================
 /**
- * Query entities by scope (parent hierarchy)
- * Uses indexScope GSI
- *
- * Note: This is a regular async function (not fabricService) because it accepts
- * complex startKey objects that can't be coerced by vocabulary's type system.
+ * List entities of a model, optionally narrowed to a scope.
+ * Requires the model to register `fabricIndex()` (pk=[model]).
  */
 async function queryByScope({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, }) {
+    const index = requireIndex(model, ["model"]);
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexScope(scope, model) + suffix;
-    return executeQuery(INDEX_SCOPE, keyValue, {
+    const pkValue = buildCompositeKey({ model }, ["model"], suffix);
+    return executeQuery(index, pkValue, {
         ascending,
         limit,
+        skPrefix: scopePrefix(scope),
         startKey,
     });
 }
 /**
- * Query a single entity by human-friendly alias
- * Uses indexAlias GSI
+ * Query a single entity by human-friendly alias.
+ * Requires the model to register `fabricIndex("alias")`.
  */
 const queryByAlias = fabricService({
     alias: "queryByAlias",
@@ -413,7 +389,11 @@ const queryByAlias = fabricService({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        scope: { type: String, description: "Scope (@ for root)" },
+        scope: {
+            type: String,
+            required: false,
+            description: "Optional scope narrower (begins_with on sk)",
+        },
     },
     service: async ({ alias, archived, deleted, model, scope, }) => {
         const aliasStr = alias;
@@ -421,52 +401,52 @@ const queryByAlias = fabricService({
         const deletedBool = deleted;
         const modelStr = model;
         const scopeStr = scope;
+        const index = requireIndex(modelStr, ["model", "alias"]);
         const suffix = calculateSuffix({
             archived: archivedBool,
             deleted: deletedBool,
         });
-        const keyValue = buildIndexAlias(scopeStr, modelStr, aliasStr) + suffix;
-        const result = await executeQuery(INDEX_ALIAS, keyValue, {
+        const pkValue = buildCompositeKey({ model: modelStr, alias: aliasStr }, ["model", "alias"], suffix);
+        const result = await executeQuery(index, pkValue, {
             limit: 1,
+            skPrefix: scopePrefix(scopeStr),
         });
         return result.items[0] ?? null;
     },
 });
 /**
- * Query entities by category classification
- * Uses indexCategory GSI
- *
- * Note: This is a regular async function (not fabricService) because it accepts
- * complex startKey objects that can't be coerced by vocabulary's type system.
+ * Query entities by category classification.
+ * Requires the model to register `fabricIndex("category")`.
  */
 async function queryByCategory({ archived = false, ascending = false, category, deleted = false, limit, model, scope, startKey, }) {
+    const index = requireIndex(model, ["model", "category"]);
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexCategory(scope, model, category) + suffix;
-    return executeQuery(INDEX_CATEGORY, keyValue, {
+    const pkValue = buildCompositeKey({ model, category }, ["model", "category"], suffix);
+    return executeQuery(index, pkValue, {
         ascending,
         limit,
+        skPrefix: scopePrefix(scope),
         startKey,
     });
 }
 /**
- * Query entities by type classification
- * Uses indexType GSI
- *
- * Note: This is a regular async function (not fabricService) because it accepts
- * complex startKey objects that can't be coerced by vocabulary's type system.
+ * Query entities by type classification.
+ * Requires the model to register `fabricIndex("type")`.
  */
 async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, type, }) {
+    const index = requireIndex(model, ["model", "type"]);
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexType(scope, model, type) + suffix;
-    return executeQuery(INDEX_TYPE, keyValue, {
+    const pkValue = buildCompositeKey({ model, type }, ["model", "type"], suffix);
+    return executeQuery(index, pkValue, {
         ascending,
         limit,
+        skPrefix: scopePrefix(scope),
         startKey,
     });
 }
 /**
- * Query a single entity by external ID
- * Uses indexXid GSI
+ * Query a single entity by external ID.
+ * Requires the model to register `fabricIndex("xid")`.
  */
 const queryByXid = fabricService({
     alias: "queryByXid",
@@ -485,7 +465,11 @@ const queryByXid = fabricService({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        scope: { type: String, description: "Scope (@ for root)" },
+        scope: {
+            type: String,
+            required: false,
+            description: "Optional scope narrower (begins_with on sk)",
+        },
         xid: { type: String, description: "External ID" },
     },
     service: async ({ archived, deleted, model, scope, xid, }) => {
@@ -494,13 +478,15 @@ const queryByXid = fabricService({
         const modelStr = model;
         const scopeStr = scope;
         const xidStr = xid;
+        const index = requireIndex(modelStr, ["model", "xid"]);
         const suffix = calculateSuffix({
             archived: archivedBool,
             deleted: deletedBool,
         });
-        const keyValue = buildIndexXid(scopeStr, modelStr, xidStr) + suffix;
-        const result = await executeQuery(INDEX_XID, keyValue, {
+        const pkValue = buildCompositeKey({ model: modelStr, xid: xidStr }, ["model", "xid"], suffix);
+        const result = await executeQuery(index, pkValue, {
             limit: 1,
+            skPrefix: scopePrefix(scopeStr),
         });
         return result.items[0] ?? null;
     },
@@ -510,53 +496,26 @@ const DEFAULT_ENDPOINT = "http://127.0.0.1:8000";
 const DEFAULT_REGION$1 = "us-east-1";
 const DEFAULT_TABLE_NAME$1 = "jaypie-local";
 // =============================================================================
-// Index to GSI Conversion
+// Index → GSI Conversion
 // =============================================================================
 /**
- * Generate an index name from pk fields (if not provided)
- */
-function generateIndexName(pk) {
-    const suffix = pk
-        .map((field) => field.charAt(0).toUpperCase() + field.slice(1))
-        .join("");
-    return `index${suffix}`;
-}
-/**
- * Collect all unique indexes from registered models
- */
-function collectAllIndexes() {
-    const indexMap = new Map();
-    for (const index of getAllRegisteredIndexes()) {
-        const name = index.name ?? generateIndexName(index.pk);
-        if (!indexMap.has(name)) {
-            indexMap.set(name, { ...index, name });
-        }
-    }
-    return Array.from(indexMap.values());
-}
-/**
- * Build attribute definitions from indexes
+ * Build attribute definitions from registered indexes.
+ * Primary key is `id` (STRING) only; GSI pk and composite sk attributes
+ * are all STRING. A single-field sk (e.g., raw `updatedAt`) is also STRING.
  */
 function buildAttributeDefinitions(indexes) {
     const attrs = new Map();
-    // Primary key attributes
-    attrs.set("model", "S");
+    // Primary key: id only
     attrs.set("id", "S");
-    attrs.set("sequence", "N");
-    // GSI attributes (partition keys are always strings)
-    for (const index of indexes) {
-        const indexName = index.name ?? generateIndexName(index.pk);
-        attrs.set(indexName, "S");
-    }
-    // Sort keys (sequence is always a number, others would be strings)
-    // Note: Currently all indexes use sequence as SK, so this is mostly future-proofing
     for (const index of indexes) {
-        const sk = index.sk ?? ["sequence"];
-        for (const skField of sk) {
-            if (!attrs.has(skField)) {
-                // Assume string unless it's sequence
-                attrs.set(skField, skField === "sequence" ? "N" : "S");
-            }
+        const { pk, sk } = getGsiAttributeNames(index);
+        // All pk attributes are composite strings
+        if (!attrs.has(pk))
+            attrs.set(pk, "S");
+        if (sk && !attrs.has(sk)) {
+            // Single-field `sequence` remains NUMBER for back-compat callers;
+            // every other sk attribute (composite or not) is STRING.
+            attrs.set(sk, sk === "sequence" ? "N" : "S");
         }
     }
     return Array.from(attrs.entries())
@@ -567,22 +526,19 @@ function buildAttributeDefinitions(indexes) {
     }));
 }
 /**
- * Build GSI definitions from indexes
+ * Build GSI definitions from registered indexes
  */
 function buildGSIs(indexes) {
     const gsiProjection = { ProjectionType: "ALL" };
     return indexes.map((index) => {
-        const indexName = index.name ?? generateIndexName(index.pk);
-        const sk = index.sk ?? ["sequence"];
-        // For GSIs, the partition key attribute name IS the index name
-        // (e.g., indexOu stores the composite key value "@#record")
+        const { pk, sk } = getGsiAttributeNames(index);
+        const keySchema = [{ AttributeName: pk, KeyType: "HASH" }];
+        if (sk) {
+            keySchema.push({ AttributeName: sk, KeyType: "RANGE" });
+        }
         return {
-            IndexName: indexName,
-            KeySchema: [
-                { AttributeName: indexName, KeyType: "HASH" },
-                // Use first SK field as the range key attribute
-                { AttributeName: sk[0], KeyType: "RANGE" },
-            ],
+            IndexName: pk,
+            KeySchema: keySchema,
             Projection: gsiProjection,
         };
     });
@@ -591,20 +547,17 @@ function buildGSIs(indexes) {
 // Table Creation
 // =============================================================================
 /**
- * DynamoDB table schema with Jaypie GSI pattern
- *
- * Collects indexes from models registered via registerModel()
+ * DynamoDB table schema with Jaypie GSI pattern.
+ * Primary key is `id` only. GSIs come from models registered via
+ * `registerModel()`, shaped by `fabricIndex()`.
  */
 function createTableParams(tableName, billingMode) {
-    const allIndexes = collectAllIndexes();
+    const allIndexes = getAllRegisteredIndexes();
     return {
         AttributeDefinitions: buildAttributeDefinitions(allIndexes),
         BillingMode: billingMode,
         GlobalSecondaryIndexes: buildGSIs(allIndexes),
-        KeySchema: [
-            { AttributeName: "model", KeyType: "HASH" },
-            { AttributeName: "id", KeyType: "RANGE" },
-        ],
+        KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
         TableName: tableName,
     };
 }
@@ -644,7 +597,6 @@ const createTableHandler = fabricService({
             region: DEFAULT_REGION$1,
         });
         try {
-            // Check if table already exists
             await client.send(new DescribeTableCommand({ TableName: tableNameStr }));
             return {
                 message: `Table "${tableNameStr}" already exists`,
@@ -657,7 +609,6 @@ const createTableHandler = fabricService({
                 throw error;
             }
         }
-        // Create the table
         const tableParams = createTableParams(tableNameStr, billingModeStr);
         await client.send(new CreateTableCommand(tableParams));
         return {