@jaypie/dynamodb 0.1.3 → 0.2.0

package/dist/cjs/constants.d.ts

@@ -1,9 +1,6 @@
-export declare const APEX = "@";
-export declare const SEPARATOR = "#";
+export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, SEPARATOR } from "@jaypie/vocabulary";
 export declare const INDEX_ALIAS = "indexAlias";
 export declare const INDEX_CLASS = "indexClass";
 export declare const INDEX_OU = "indexOu";
 export declare const INDEX_TYPE = "indexType";
 export declare const INDEX_XID = "indexXid";
-export declare const ARCHIVED_SUFFIX = "#archived";
-export declare const DELETED_SUFFIX = "#deleted";

package/dist/cjs/entities.d.ts

@@ -1,28 +1,28 @@
-import type { FabricEntity } from "./types.js";
+import type { StorableEntity } from "./types.js";
 /**
  * Get a single entity by primary key
  */
-export declare const getEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, FabricEntity | null>;
+export declare const getEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, StorableEntity | null>;
 /**
  * Put (create or replace) an entity
  * 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.
  */
 export declare function putEntity({ entity, }: {
-    entity: FabricEntity;
-}): Promise<FabricEntity>;
+    entity: StorableEntity;
+}): Promise<StorableEntity>;
 /**
  * Update an existing 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.
  */
 export declare function updateEntity({ entity, }: {
-    entity: FabricEntity;
-}): Promise<FabricEntity>;
+    entity: StorableEntity;
+}): Promise<StorableEntity>;
 /**
  * Soft delete an entity by setting deletedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state

package/dist/cjs/index.cjs

@@ -83,19 +83,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}")
@@ -103,7 +101,7 @@ const DELETED_SUFFIX = "#deleted";
  * @returns Composite key: "{ou}#{model}"
  */
 function buildIndexOu(ou, model) {
-    return `${ou}${SEPARATOR}${model}`;
+    return `${ou}${vocabulary.SEPARATOR}${model}`;
 }
 /**
  * Build the indexAlias key for human-friendly lookups
@@ -113,7 +111,7 @@ function buildIndexOu(ou, model) {
  * @returns Composite key: "{ou}#{model}#{alias}"
  */
 function buildIndexAlias(ou, model, alias) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;
+    return `${ou}${vocabulary.SEPARATOR}${model}${vocabulary.SEPARATOR}${alias}`;
 }
 /**
  * Build the indexClass key for category filtering
@@ -123,7 +121,7 @@ function buildIndexAlias(ou, model, alias) {
  * @returns Composite key: "{ou}#{model}#{class}"
  */
 function buildIndexClass(ou, model, recordClass) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
+    return `${ou}${vocabulary.SEPARATOR}${model}${vocabulary.SEPARATOR}${recordClass}`;
 }
 /**
  * Build the indexType key for type filtering
@@ -133,7 +131,7 @@ function buildIndexClass(ou, model, recordClass) {
  * @returns Composite key: "{ou}#{model}#{type}"
  */
 function buildIndexType(ou, model, type) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;
+    return `${ou}${vocabulary.SEPARATOR}${model}${vocabulary.SEPARATOR}${type}`;
 }
 /**
  * Build the indexXid key for external ID lookups
@@ -143,7 +141,21 @@ function buildIndexType(ou, model, type) {
  * @returns Composite key: "{ou}#{model}#{xid}"
  */
 function buildIndexXid(ou, model, xid) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+    return `${ou}${vocabulary.SEPARATOR}${model}${vocabulary.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 vocabulary.buildCompositeKey(entity, fields, suffix);
 }
 /**
  * Calculate the organizational unit from a parent reference
@@ -152,12 +164,16 @@ function buildIndexXid(ou, model, xid) {
  */
 function calculateOu(parent) {
     if (!parent) {
-        return APEX;
+        return vocabulary.APEX;
     }
-    return `${parent.model}${SEPARATOR}${parent.id}`;
+    return vocabulary.calculateOu(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
@@ -169,27 +185,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 = vocabulary.getModelIndexes(entity.model);
+    // Cast through unknown to bridge the type gap between StorableEntity and IndexableEntity
+    return vocabulary.populateIndexKeys(entity, indexes, suffix);
 }
 
 /**
@@ -199,13 +197,13 @@ function calculateEntitySuffix(entity) {
     const hasArchived = Boolean(entity.archivedAt);
     const hasDeleted = Boolean(entity.deletedAt);
     if (hasArchived && hasDeleted) {
-        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+        return vocabulary.ARCHIVED_SUFFIX + vocabulary.DELETED_SUFFIX;
     }
     if (hasArchived) {
-        return ARCHIVED_SUFFIX;
+        return vocabulary.ARCHIVED_SUFFIX;
     }
     if (hasDeleted) {
-        return DELETED_SUFFIX;
+        return vocabulary.DELETED_SUFFIX;
     }
     return "";
 }
@@ -235,7 +233,7 @@ const getEntity = vocabulary.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();
@@ -254,7 +252,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();
@@ -372,15 +370,15 @@ const destroyEntity = vocabulary.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;
+        return vocabulary.ARCHIVED_SUFFIX + vocabulary.DELETED_SUFFIX;
     }
     if (archived) {
-        return ARCHIVED_SUFFIX;
+        return vocabulary.ARCHIVED_SUFFIX;
     }
     if (deleted) {
-        return DELETED_SUFFIX;
+        return vocabulary.DELETED_SUFFIX;
     }
     return "";
 }
@@ -419,7 +417,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,
@@ -457,7 +455,7 @@ const queryByAlias = vocabulary.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,
@@ -473,7 +471,7 @@ const queryByAlias = vocabulary.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,
@@ -489,7 +487,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,
@@ -527,7 +525,7 @@ const queryByXid = vocabulary.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,
@@ -536,6 +534,172 @@ const queryByXid = vocabulary.serviceHandler({
     },
 });
 
+/**
+ * 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 vocabulary.ARCHIVED_SUFFIX + vocabulary.DELETED_SUFFIX;
+    }
+    if (archived) {
+        return vocabulary.ARCHIVED_SUFFIX;
+    }
+    if (deleted) {
+        return vocabulary.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 errors.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 = vocabulary.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 libDynamodb.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
  *
@@ -685,16 +849,33 @@ async function exportEntitiesToJson(model, ou, pretty = true) {
     return pretty ? JSON.stringify(entities, null, 2) : JSON.stringify(entities);
 }
 
-exports.APEX = APEX;
-exports.ARCHIVED_SUFFIX = ARCHIVED_SUFFIX;
-exports.DELETED_SUFFIX = DELETED_SUFFIX;
+Object.defineProperty(exports, "APEX", {
+    enumerable: true,
+    get: function () { return vocabulary.APEX; }
+});
+Object.defineProperty(exports, "ARCHIVED_SUFFIX", {
+    enumerable: true,
+    get: function () { return vocabulary.ARCHIVED_SUFFIX; }
+});
+Object.defineProperty(exports, "DEFAULT_INDEXES", {
+    enumerable: true,
+    get: function () { return vocabulary.DEFAULT_INDEXES; }
+});
+Object.defineProperty(exports, "DELETED_SUFFIX", {
+    enumerable: true,
+    get: function () { return vocabulary.DELETED_SUFFIX; }
+});
+Object.defineProperty(exports, "SEPARATOR", {
+    enumerable: true,
+    get: function () { return vocabulary.SEPARATOR; }
+});
 exports.INDEX_ALIAS = INDEX_ALIAS;
 exports.INDEX_CLASS = INDEX_CLASS;
 exports.INDEX_OU = INDEX_OU;
 exports.INDEX_TYPE = INDEX_TYPE;
 exports.INDEX_XID = INDEX_XID;
-exports.SEPARATOR = SEPARATOR;
 exports.archiveEntity = archiveEntity;
+exports.buildCompositeKey = buildCompositeKey;
 exports.buildIndexAlias = buildIndexAlias;
 exports.buildIndexClass = buildIndexClass;
 exports.buildIndexOu = buildIndexOu;
@@ -712,6 +893,7 @@ exports.indexEntity = indexEntity;
 exports.initClient = initClient;
 exports.isInitialized = isInitialized;
 exports.putEntity = putEntity;
+exports.query = query;
 exports.queryByAlias = queryByAlias;
 exports.queryByClass = queryByClass;
 exports.queryByOu = queryByOu;