@jaypie/dynamodb 0.4.4 → 0.6.0

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, TransactWriteCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
 import { ConfigurationError } from '@jaypie/errors';
-import { getModelIndexes, populateIndexKeys, SEPARATOR, buildCompositeKey as buildCompositeKey$1, APEX, calculateScope as calculateScope$1, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX } from '@jaypie/fabric';
+import { getModelIndexes, populateIndexKeys, buildCompositeKey as buildCompositeKey$1, APEX, calculateScope as calculateScope$1, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX, getGsiAttributeNames, SEPARATOR } from '@jaypie/fabric';
 export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, SEPARATOR } from '@jaypie/fabric';
 
 // Environment variable names
@@ -82,69 +82,9 @@ function resetClient() {
     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}"
- */
-function buildIndexXid(scope, model, xid) {
-    return `${scope}${SEPARATOR}${model}${SEPARATOR}${xid}`;
-}
-// =============================================================================
-// New Vocabulary-Based Functions
-// =============================================================================
 /**
  * Build a composite key from entity fields
  *
@@ -168,24 +108,30 @@ function calculateScope(parent) {
     return calculateScope$1(parent);
 }
 /**
- * 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 (createEntity, 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);
 }
 
 /**
@@ -206,20 +152,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);
@@ -227,39 +172,38 @@ 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.
+ * Create an entity. Fails the conditional write if `id` already exists,
+ * returning `null` instead of throwing. Use `updateEntity` to overwrite.
+ * `indexEntity` auto-bumps `updatedAt` and backfills `createdAt`.
  */
-async function putEntity({ entity, }) {
+async function createEntity({ entity, }) {
     const docClient = getDocClient();
     const tableName = getTableName();
-    // Auto-populate index keys
     const indexedEntity = indexEntity(entity);
     const command = new PutCommand({
+        ConditionExpression: "attribute_not_exists(id)",
         Item: indexedEntity,
         TableName: tableName,
     });
-    await docClient.send(command);
+    try {
+        await docClient.send(command);
+    }
+    catch (error) {
+        if (error?.name === "ConditionalCheckFailedException") {
+            return null;
+        }
+        throw error;
+    }
     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,
@@ -275,25 +219,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({
@@ -312,25 +252,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({
@@ -349,14 +284,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);
@@ -382,11 +316,15 @@ async function transactWriteEntities({ entities, }) {
     await docClient.send(command);
 }
 
+// =============================================================================
+// 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$1({ archived, deleted, }) {
+function calculateSuffix({ archived, deleted, }) {
     if (archived && deleted) {
         return ARCHIVED_SUFFIX + DELETED_SUFFIX;
     }
@@ -399,22 +337,51 @@ function calculateSuffix$1({ 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.
  */
-async function executeQuery(indexName, keyValue, options = {}) {
-    const { ascending = false, limit, startKey } = options;
+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(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,
@@ -425,25 +392,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 suffix = calculateSuffix$1({ archived, deleted });
-    const keyValue = buildIndexScope(scope, model) + suffix;
-    return executeQuery(INDEX_SCOPE, keyValue, {
+    const index = requireIndex(model, ["model"]);
+    const suffix = calculateSuffix({ archived, deleted });
+    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",
@@ -463,7 +435,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;
@@ -471,52 +447,52 @@ const queryByAlias = fabricService({
         const deletedBool = deleted;
         const modelStr = model;
         const scopeStr = scope;
-        const suffix = calculateSuffix$1({
+        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 suffix = calculateSuffix$1({ archived, deleted });
-    const keyValue = buildIndexCategory(scope, model, category) + suffix;
-    return executeQuery(INDEX_CATEGORY, keyValue, {
+    const index = requireIndex(model, ["model", "category"]);
+    const suffix = calculateSuffix({ archived, deleted });
+    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 suffix = calculateSuffix$1({ archived, deleted });
-    const keyValue = buildIndexType(scope, model, type) + suffix;
-    return executeQuery(INDEX_TYPE, keyValue, {
+    const index = requireIndex(model, ["model", "type"]);
+    const suffix = calculateSuffix({ archived, deleted });
+    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",
@@ -535,7 +511,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, }) => {
@@ -544,13 +524,15 @@ const queryByXid = fabricService({
         const modelStr = model;
         const scopeStr = scope;
         const xidStr = xid;
-        const suffix = calculateSuffix$1({
+        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;
     },
@@ -564,162 +546,77 @@ const queryByXid = fabricService({
  * removing the need to know which specific GSI to use.
  */
 // =============================================================================
-// Helper Functions
+// Index Selection
 // =============================================================================
 /**
- * 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.scope !== undefined) {
-        result.scope = params.scope;
-    }
-    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
+ * 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(", ")}]`)
+ * Every model-level index has `model` as its first pk field. The picker
+ * prefers the most specific index whose remaining pk fields are all
+ * satisfied by the filter.
+ */
+function selectBestIndex(indexes, filter) {
+    // Candidates: indexes whose pk starts with "model" and whose remaining
+    // fields are all present in the filter.
+    const candidates = indexes.filter((index) => {
+        if (index.pk.length === 0 || index.pk[0] !== "model")
+            return false;
+        for (let i = 1; i < index.pk.length; i++) {
+            if (filter[index.pk[i]] === undefined)
+                return false;
+        }
+        return true;
+    });
+    if (candidates.length === 0) {
+        const available = indexes
+            .map((i) => `[${i.pk.join(", ")}]`)
             .join(", ");
-        const providedFields = Object.keys(filterFields).join(", ");
-        throw new ConfigurationError(`No index matches filter fields. ` +
-            `Provided: ${providedFields}. ` +
-            `Available indexes: ${availableIndexes}`);
+        const provided = Object.keys(filter).join(", ") || "(none)";
+        throw new ConfigurationError(`No index matches filter for model. ` +
+            `Filter fields: ${provided}. Available indexes: ${available}`);
     }
-    // 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;
+    // Prefer the most specific index (longest pk).
+    candidates.sort((a, b) => b.pk.length - a.pk.length);
+    return candidates[0];
 }
 // =============================================================================
 // 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.
+ * Query entities with automatic index selection.
  *
  * @example
- * // Uses indexScope (pk: ["scope", "model"])
- * const allMessages = await query({ model: "message", scope: `chat#${chatId}` });
+ *   // Uses indexModel (pk: ["model"]), optionally narrowed by scope
+ *   const records = await query({ model: "record", scope: "@" });
  *
  * @example
- * // Uses indexAlias (pk: ["scope", "model", "alias"])
- * const byAlias = await query({
- *   model: "record",
- *   scope: "@",
- *   filter: { alias: "my-record" },
- * });
+ *   // Uses indexModelAlias (pk: ["model", "alias"])
+ *   const byAlias = await query({
+ *     model: "record",
+ *     scope: "@",
+ *     filter: { alias: "my-record" },
+ *   });
  *
  * @example
- * // Uses a custom registered index if model has one
- * const byChat = await query({
- *   model: "message",
- *   filter: { chatId: "abc-123" },
- * });
+ *   // Cross-scope listing (no scope narrower)
+ *   const all = await query({ model: "record" });
  */
 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
+    const { archived = false, ascending = false, deleted = false, filter, limit, model, scope, startKey, } = params;
     const indexes = getModelIndexes(model);
-    // Select the best matching index
+    const filterFields = {
+        model,
+        ...filter,
+    };
     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 suffix = calculateSuffix({ archived, deleted });
+    const pkValue = buildCompositeKey(filterFields, selectedIndex.pk, suffix);
+    return executeQuery(selectedIndex, pkValue, {
+        ascending,
+        limit,
+        skPrefix: scopePrefix(scope),
+        startKey,
     });
-    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}`;
 }
 
 /**
@@ -741,19 +638,15 @@ async function seedEntityIfNotExists(entity) {
     if (existing) {
         return false;
     }
-    // Generate required fields if missing
-    const now = new Date().toISOString();
+    // Generate required fields if missing; indexEntity manages timestamps
     const completeEntity = {
-        createdAt: entity.createdAt ?? now,
         id: entity.id ?? crypto.randomUUID(),
         model: entity.model,
         name: entity.name ?? entity.alias,
         scope: entity.scope,
-        sequence: entity.sequence ?? Date.now(),
-        updatedAt: entity.updatedAt ?? now,
         ...entity,
     };
-    await putEntity({ entity: completeEntity });
+    await createEntity({ entity: completeEntity });
     return true;
 }
 /**
@@ -782,6 +675,7 @@ async function seedEntities(entities, options = {}) {
                 throw new Error("Entity must have model and scope");
             }
             // For entities with alias, check existence
+            let isReplace = false;
             if (entity.alias) {
                 const existing = await queryByAlias({
                     alias: entity.alias,
@@ -795,25 +689,27 @@ async function seedEntities(entities, options = {}) {
                 // If replacing, use existing ID to update rather than create new
                 if (existing && replace) {
                     entity.id = existing.id;
+                    isReplace = true;
                 }
             }
             if (dryRun) {
                 result.created.push(alias);
                 continue;
             }
-            // Generate required fields if missing
-            const now = new Date().toISOString();
+            // Generate required fields if missing; indexEntity manages timestamps
             const completeEntity = {
-                createdAt: entity.createdAt ?? now,
                 id: entity.id ?? crypto.randomUUID(),
                 model: entity.model,
                 name: entity.name ?? entity.alias ?? "Unnamed",
                 scope: entity.scope,
-                sequence: entity.sequence ?? Date.now(),
-                updatedAt: entity.updatedAt ?? now,
                 ...entity,
             };
-            await putEntity({ entity: completeEntity });
+            if (isReplace) {
+                await updateEntity({ entity: completeEntity });
+            }
+            else {
+                await createEntity({ entity: completeEntity });
+            }
             result.created.push(alias);
         }
         catch (error) {
@@ -871,5 +767,5 @@ async function exportEntitiesToJson(model, scope, pretty = true) {
     return pretty ? JSON.stringify(entities, null, 2) : JSON.stringify(entities);
 }
 
-export { INDEX_ALIAS, INDEX_CATEGORY, INDEX_SCOPE, INDEX_TYPE, INDEX_XID, archiveEntity, buildCompositeKey, buildIndexAlias, buildIndexCategory, buildIndexScope, buildIndexType, buildIndexXid, calculateScope, deleteEntity, destroyEntity, exportEntities, exportEntitiesToJson, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, putEntity, query, queryByAlias, queryByCategory, queryByScope, queryByType, queryByXid, resetClient, seedEntities, seedEntityIfNotExists, transactWriteEntities, updateEntity };
+export { archiveEntity, buildCompositeKey, calculateScope, createEntity, deleteEntity, destroyEntity, exportEntities, exportEntitiesToJson, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, query, queryByAlias, queryByCategory, queryByScope, queryByType, queryByXid, resetClient, seedEntities, seedEntityIfNotExists, transactWriteEntities, updateEntity };
 //# sourceMappingURL=index.js.map