@jaypie/dynamodb 0.1.3 → 0.3.0

package/dist/cjs/index.cjs

@@ -3,7 +3,7 @@
 var clientDynamodb = require('@aws-sdk/client-dynamodb');
 var libDynamodb = require('@aws-sdk/lib-dynamodb');
 var errors = require('@jaypie/errors');
-var vocabulary = require('@jaypie/vocabulary');
+var fabric = require('@jaypie/fabric');
 
 // Environment variable names
 const ENV_AWS_REGION = "AWS_REGION";
@@ -83,82 +83,98 @@ 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 fabric
+// GSI names (derived from DEFAULT_INDEXES)
 const INDEX_ALIAS = "indexAlias";
 const INDEX_CLASS = "indexClass";
-const INDEX_OU = "indexOu";
+const INDEX_SCOPE = "indexScope";
 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}")
+ * 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: "{ou}#{model}"
+ * @returns Composite key: "{scope}#{model}"
  */
-function buildIndexOu(ou, model) {
-    return `${ou}${SEPARATOR}${model}`;
+function buildIndexScope(scope, model) {
+    return `${scope}${fabric.SEPARATOR}${model}`;
 }
 /**
  * Build the indexAlias key for human-friendly lookups
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param alias - The human-friendly alias
- * @returns Composite key: "{ou}#{model}#{alias}"
+ * @returns Composite key: "{scope}#{model}#{alias}"
  */
-function buildIndexAlias(ou, model, alias) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;
+function buildIndexAlias(scope, model, alias) {
+    return `${scope}${fabric.SEPARATOR}${model}${fabric.SEPARATOR}${alias}`;
 }
 /**
  * Build the indexClass key for category filtering
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param recordClass - The category classification
- * @returns Composite key: "{ou}#{model}#{class}"
+ * @returns Composite key: "{scope}#{model}#{class}"
  */
-function buildIndexClass(ou, model, recordClass) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
+function buildIndexClass(scope, model, recordClass) {
+    return `${scope}${fabric.SEPARATOR}${model}${fabric.SEPARATOR}${recordClass}`;
 }
 /**
  * Build the indexType key for type filtering
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param type - The type classification
- * @returns Composite key: "{ou}#{model}#{type}"
+ * @returns Composite key: "{scope}#{model}#{type}"
  */
-function buildIndexType(ou, model, type) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;
+function buildIndexType(scope, model, type) {
+    return `${scope}${fabric.SEPARATOR}${model}${fabric.SEPARATOR}${type}`;
 }
 /**
  * Build the indexXid key for external ID lookups
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param xid - The external ID
- * @returns Composite key: "{ou}#{model}#{xid}"
+ * @returns Composite key: "{scope}#{model}#{xid}"
  */
-function buildIndexXid(ou, model, xid) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+function buildIndexXid(scope, model, xid) {
+    return `${scope}${fabric.SEPARATOR}${model}${fabric.SEPARATOR}${xid}`;
 }
+// =============================================================================
+// New Vocabulary-Based Functions
+// =============================================================================
 /**
- * Calculate the organizational unit from a parent reference
+ * 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 fabric.buildCompositeKey(entity, fields, suffix);
+}
+/**
+ * Calculate the scope from a parent reference
  * @param parent - Optional parent entity reference
  * @returns APEX ("@") if no parent, otherwise "{parent.model}#{parent.id}"
  */
-function calculateOu(parent) {
+function calculateScope(parent) {
     if (!parent) {
-        return APEX;
+        return fabric.APEX;
     }
-    return `${parent.model}${SEPARATOR}${parent.id}`;
+    return fabric.calculateScope(parent);
 }
 /**
  * Auto-populate GSI index keys on an entity
- * - indexOu is always populated from ou + model
+ *
+ * Uses the model's registered indexes (from vocabulary registry) or
+ * DEFAULT_INDEXES if no custom indexes are registered.
+ *
+ * - indexScope is always populated from scope + model
  * - indexAlias is populated only when alias is present
  * - indexClass is populated only when class is present
  * - indexType is populated only when type 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 = fabric.getModelIndexes(entity.model);
+    // Cast through unknown to bridge the type gap between StorableEntity and IndexableModel
+    return fabric.populateIndexKeys(entity, indexes, suffix);
 }
 
 /**
@@ -199,20 +197,20 @@ function calculateEntitySuffix(entity) {
     const hasArchived = Boolean(entity.archivedAt);
     const hasDeleted = Boolean(entity.deletedAt);
     if (hasArchived && hasDeleted) {
-        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+        return fabric.ARCHIVED_SUFFIX + fabric.DELETED_SUFFIX;
     }
     if (hasArchived) {
-        return ARCHIVED_SUFFIX;
+        return fabric.ARCHIVED_SUFFIX;
     }
     if (hasDeleted) {
-        return DELETED_SUFFIX;
+        return fabric.DELETED_SUFFIX;
     }
     return "";
 }
 /**
  * Get a single entity by primary key
  */
-const getEntity = vocabulary.serviceHandler({
+const getEntity = fabric.fabricService({
     alias: "getEntity",
     description: "Get a single entity by primary key",
     input: {
@@ -234,8 +232,8 @@ const getEntity = vocabulary.serviceHandler({
  * 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.
+ * 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.
  */
 async function putEntity({ entity, }) {
     const docClient = getDocClient();
@@ -253,8 +251,8 @@ async function putEntity({ entity, }) {
  * 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.
+ * 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.
  */
 async function updateEntity({ entity, }) {
     const docClient = getDocClient();
@@ -275,7 +273,7 @@ async function updateEntity({ entity, }) {
  * Soft delete an entity by setting deletedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const deleteEntity = vocabulary.serviceHandler({
+const deleteEntity = fabric.fabricService({
     alias: "deleteEntity",
     description: "Soft delete an entity (sets deletedAt timestamp)",
     input: {
@@ -312,7 +310,7 @@ const deleteEntity = vocabulary.serviceHandler({
  * Archive an entity by setting archivedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const archiveEntity = vocabulary.serviceHandler({
+const archiveEntity = fabric.fabricService({
     alias: "archiveEntity",
     description: "Archive an entity (sets archivedAt timestamp)",
     input: {
@@ -349,7 +347,7 @@ const archiveEntity = vocabulary.serviceHandler({
  * Hard delete an entity (permanently removes from table)
  * Use with caution - prefer deleteEntity for soft delete
  */
-const destroyEntity = vocabulary.serviceHandler({
+const destroyEntity = fabric.fabricService({
     alias: "destroyEntity",
     description: "Hard delete an entity (permanently removes from table)",
     input: {
@@ -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 fabric.ARCHIVED_SUFFIX + fabric.DELETED_SUFFIX;
     }
     if (archived) {
-        return ARCHIVED_SUFFIX;
+        return fabric.ARCHIVED_SUFFIX;
     }
     if (deleted) {
-        return DELETED_SUFFIX;
+        return fabric.DELETED_SUFFIX;
     }
     return "";
 }
@@ -412,16 +410,16 @@ async function executeQuery(indexName, keyValue, options = {}) {
     };
 }
 /**
- * Query entities by organizational unit (parent hierarchy)
- * Uses indexOu GSI
+ * Query entities by scope (parent hierarchy)
+ * Uses indexScope GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * 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.
  */
-async function queryByOu({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, }) {
-    const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexOu(ou, model) + suffix;
-    return executeQuery(INDEX_OU, keyValue, {
+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, {
         ascending,
         limit,
         startKey,
@@ -431,7 +429,7 @@ async function queryByOu({ archived = false, ascending = false, deleted = false,
  * Query a single entity by human-friendly alias
  * Uses indexAlias GSI
  */
-const queryByAlias = vocabulary.serviceHandler({
+const queryByAlias = fabric.fabricService({
     alias: "queryByAlias",
     description: "Query a single entity by human-friendly alias",
     input: {
@@ -449,16 +447,19 @@ const queryByAlias = vocabulary.serviceHandler({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
     },
-    service: async ({ alias, archived, deleted, model, ou, }) => {
+    service: async ({ alias, archived, deleted, model, scope, }) => {
         const aliasStr = alias;
         const archivedBool = archived;
         const deletedBool = deleted;
         const modelStr = model;
-        const ouStr = ou;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
-        const keyValue = buildIndexAlias(ouStr, modelStr, aliasStr) + suffix;
+        const scopeStr = scope;
+        const suffix = calculateSuffix$1({
+            archived: archivedBool,
+            deleted: deletedBool,
+        });
+        const keyValue = buildIndexAlias(scopeStr, modelStr, aliasStr) + suffix;
         const result = await executeQuery(INDEX_ALIAS, keyValue, {
             limit: 1,
         });
@@ -469,12 +470,12 @@ const queryByAlias = vocabulary.serviceHandler({
  * Query entities by category classification
  * Uses indexClass GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * 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.
  */
-async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, ou, recordClass, startKey, }) {
-    const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
+async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, scope, recordClass, startKey, }) {
+    const suffix = calculateSuffix$1({ archived, deleted });
+    const keyValue = buildIndexClass(scope, model, recordClass) + suffix;
     return executeQuery(INDEX_CLASS, keyValue, {
         ascending,
         limit,
@@ -485,12 +486,12 @@ async function queryByClass({ archived = false, ascending = false, deleted = fal
  * Query entities by type classification
  * Uses indexType GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * 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.
  */
-async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, type, }) {
-    const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexType(ou, model, type) + suffix;
+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, {
         ascending,
         limit,
@@ -501,7 +502,7 @@ async function queryByType({ archived = false, ascending = false, deleted = fals
  * Query a single entity by external ID
  * Uses indexXid GSI
  */
-const queryByXid = vocabulary.serviceHandler({
+const queryByXid = fabric.fabricService({
     alias: "queryByXid",
     description: "Query a single entity by external ID",
     input: {
@@ -518,17 +519,20 @@ const queryByXid = vocabulary.serviceHandler({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         xid: { type: String, description: "External ID" },
     },
-    service: async ({ archived, deleted, model, ou, xid, }) => {
+    service: async ({ archived, deleted, model, scope, xid, }) => {
         const archivedBool = archived;
         const deletedBool = deleted;
         const modelStr = model;
-        const ouStr = ou;
+        const scopeStr = scope;
         const xidStr = xid;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
-        const keyValue = buildIndexXid(ouStr, modelStr, xidStr) + suffix;
+        const suffix = calculateSuffix$1({
+            archived: archivedBool,
+            deleted: deletedBool,
+        });
+        const keyValue = buildIndexXid(scopeStr, modelStr, xidStr) + suffix;
         const result = await executeQuery(INDEX_XID, keyValue, {
             limit: 1,
         });
@@ -536,21 +540,187 @@ 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 fabric.ARCHIVED_SUFFIX + fabric.DELETED_SUFFIX;
+    }
+    if (archived) {
+        return fabric.ARCHIVED_SUFFIX;
+    }
+    if (deleted) {
+        return fabric.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
+ *
+ * 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 indexScope (pk: ["scope", "model"])
+ * const allMessages = await query({ model: "message", scope: `chat#${chatId}` });
+ *
+ * @example
+ * // Uses indexAlias (pk: ["scope", "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" },
+ * });
+ */
+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 = fabric.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
  *
- * @param entity - Partial entity with at least alias, model, and ou
+ * @param entity - Partial entity with at least alias, model, and scope
  * @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");
+    if (!entity.alias || !entity.model || !entity.scope) {
+        throw new Error("Entity must have alias, model, and scope to check existence");
     }
     // Check if entity already exists
     const existing = await queryByAlias({
         alias: entity.alias,
         model: entity.model,
-        ou: entity.ou,
+        scope: entity.scope,
     });
     if (existing) {
         return false;
@@ -562,7 +732,7 @@ async function seedEntityIfNotExists(entity) {
         id: entity.id ?? crypto.randomUUID(),
         model: entity.model,
         name: entity.name ?? entity.alias,
-        ou: entity.ou,
+        scope: entity.scope,
         sequence: entity.sequence ?? Date.now(),
         updatedAt: entity.updatedAt ?? now,
         ...entity,
@@ -592,15 +762,15 @@ async function seedEntities(entities, options = {}) {
     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");
+            if (!entity.model || !entity.scope) {
+                throw new Error("Entity must have model and scope");
             }
             // For entities with alias, check existence
             if (entity.alias) {
                 const existing = await queryByAlias({
                     alias: entity.alias,
                     model: entity.model,
-                    ou: entity.ou,
+                    scope: entity.scope,
                 });
                 if (existing && !replace) {
                     result.skipped.push(alias);
@@ -622,7 +792,7 @@ async function seedEntities(entities, options = {}) {
                 id: entity.id ?? crypto.randomUUID(),
                 model: entity.model,
                 name: entity.name ?? entity.alias ?? "Unnamed",
-                ou: entity.ou,
+                scope: entity.scope,
                 sequence: entity.sequence ?? Date.now(),
                 updatedAt: entity.updatedAt ?? now,
                 ...entity,
@@ -638,27 +808,27 @@ async function seedEntities(entities, options = {}) {
     return result;
 }
 /**
- * Export entities by model and organizational unit
+ * Export entities by model and scope
  *
- * - Paginates through all matching entities via queryByOu
+ * - Paginates through all matching entities via queryByScope
  * - Returns entities sorted by sequence (ascending)
  *
  * @param model - The entity model name
- * @param ou - The organizational unit
+ * @param scope - The scope (APEX or "{parent.model}#{parent.id}")
  * @param limit - Optional maximum number of entities to export
  * @returns Export result with entities and count
  */
-async function exportEntities(model, ou, limit) {
+async function exportEntities(model, scope, limit) {
     const entities = [];
     let startKey;
     let remaining = limit;
     do {
         const batchLimit = remaining !== undefined ? Math.min(remaining, 100) : undefined;
-        const { items, lastEvaluatedKey } = await queryByOu({
+        const { items, lastEvaluatedKey } = await queryByScope({
             ascending: true,
             limit: batchLimit,
             model,
-            ou,
+            scope,
             startKey,
         });
         entities.push(...items);
@@ -676,31 +846,48 @@ async function exportEntities(model, ou, limit) {
  * Export entities as a JSON string
  *
  * @param model - The entity model name
- * @param ou - The organizational unit
+ * @param scope - The scope (APEX or "{parent.model}#{parent.id}")
  * @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);
+async function exportEntitiesToJson(model, scope, pretty = true) {
+    const { entities } = await exportEntities(model, scope);
     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 fabric.APEX; }
+});
+Object.defineProperty(exports, "ARCHIVED_SUFFIX", {
+    enumerable: true,
+    get: function () { return fabric.ARCHIVED_SUFFIX; }
+});
+Object.defineProperty(exports, "DEFAULT_INDEXES", {
+    enumerable: true,
+    get: function () { return fabric.DEFAULT_INDEXES; }
+});
+Object.defineProperty(exports, "DELETED_SUFFIX", {
+    enumerable: true,
+    get: function () { return fabric.DELETED_SUFFIX; }
+});
+Object.defineProperty(exports, "SEPARATOR", {
+    enumerable: true,
+    get: function () { return fabric.SEPARATOR; }
+});
 exports.INDEX_ALIAS = INDEX_ALIAS;
 exports.INDEX_CLASS = INDEX_CLASS;
-exports.INDEX_OU = INDEX_OU;
+exports.INDEX_SCOPE = INDEX_SCOPE;
 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;
+exports.buildIndexScope = buildIndexScope;
 exports.buildIndexType = buildIndexType;
 exports.buildIndexXid = buildIndexXid;
-exports.calculateOu = calculateOu;
+exports.calculateScope = calculateScope;
 exports.deleteEntity = deleteEntity;
 exports.destroyEntity = destroyEntity;
 exports.exportEntities = exportEntities;
@@ -712,9 +899,10 @@ exports.indexEntity = indexEntity;
 exports.initClient = initClient;
 exports.isInitialized = isInitialized;
 exports.putEntity = putEntity;
+exports.query = query;
 exports.queryByAlias = queryByAlias;
 exports.queryByClass = queryByClass;
-exports.queryByOu = queryByOu;
+exports.queryByScope = queryByScope;
 exports.queryByType = queryByType;
 exports.queryByXid = queryByXid;
 exports.resetClient = resetClient;