@jaypie/dynamodb 0.2.0 → 0.3.0

package/dist/esm/entities.d.ts

@@ -2,12 +2,12 @@ import type { StorableEntity } from "./types.js";
 /**
  * Get a single entity by primary key
  */
-export declare const getEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, StorableEntity | null>;
+export declare const getEntity: import("@jaypie/fabric").Service<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
+ * 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.
  */
 export declare function putEntity({ entity, }: {
@@ -17,7 +17,7 @@ export declare 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
+ * 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.
  */
 export declare function updateEntity({ entity, }: {
@@ -27,14 +27,14 @@ export declare function updateEntity({ entity, }: {
  * Soft delete an entity by setting deletedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-export declare const deleteEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, boolean>;
+export declare const deleteEntity: import("@jaypie/fabric").Service<Record<string, unknown>, boolean>;
 /**
  * Archive an entity by setting archivedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-export declare const archiveEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, boolean>;
+export declare const archiveEntity: import("@jaypie/fabric").Service<Record<string, unknown>, boolean>;
 /**
  * Hard delete an entity (permanently removes from table)
  * Use with caution - prefer deleteEntity for soft delete
  */
-export declare const destroyEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, boolean>;
+export declare const destroyEntity: import("@jaypie/fabric").Service<Record<string, unknown>, boolean>;

package/dist/esm/index.d.ts

@@ -1,8 +1,8 @@
 export { getDocClient, getTableName, initClient, isInitialized, resetClient, } from "./client.js";
-export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, INDEX_ALIAS, INDEX_CLASS, INDEX_OU, INDEX_TYPE, INDEX_XID, SEPARATOR, } from "./constants.js";
+export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, INDEX_ALIAS, INDEX_CLASS, INDEX_SCOPE, INDEX_TYPE, INDEX_XID, SEPARATOR, } from "./constants.js";
 export { archiveEntity, deleteEntity, destroyEntity, getEntity, putEntity, updateEntity, } from "./entities.js";
-export { buildCompositeKey, buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, DEFAULT_INDEXES, indexEntity, } from "./keyBuilders.js";
-export { queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, } from "./queries.js";
+export { buildCompositeKey, buildIndexAlias, buildIndexClass, buildIndexScope, buildIndexType, buildIndexXid, calculateScope, DEFAULT_INDEXES, indexEntity, } from "./keyBuilders.js";
+export { queryByAlias, queryByClass, queryByScope, queryByType, queryByXid, } from "./queries.js";
 export { query } from "./query.js";
 export type { QueryParams } from "./query.js";
 export { exportEntities, exportEntitiesToJson, seedEntities, seedEntityIfNotExists, } from "./seedExport.js";

package/dist/esm/index.js

@@ -1,8 +1,8 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
 import { ConfigurationError } from '@jaypie/errors';
-import { getModelIndexes, populateIndexKeys, SEPARATOR, buildCompositeKey as buildCompositeKey$1, APEX, calculateOu as calculateOu$1, serviceHandler, ARCHIVED_SUFFIX, DELETED_SUFFIX } from '@jaypie/vocabulary';
-export { APEX, ARCHIVED_SUFFIX, DEFAULT_INDEXES, DELETED_SUFFIX, SEPARATOR } from '@jaypie/vocabulary';
+import { getModelIndexes, populateIndexKeys, SEPARATOR, buildCompositeKey as buildCompositeKey$1, APEX, calculateScope as calculateScope$1, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX } from '@jaypie/fabric';
+export { APEX, ARCHIVED_SUFFIX, DEFAULT_INDEXES, DELETED_SUFFIX, SEPARATOR } from '@jaypie/fabric';
 
 // Environment variable names
 const ENV_AWS_REGION = "AWS_REGION";
@@ -82,11 +82,11 @@ function resetClient() {
     tableName = null;
 }
 
-// Re-export shared constants from vocabulary
+// 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";
 
@@ -94,53 +94,53 @@ const INDEX_XID = "indexXid";
 // 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}${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}${SEPARATOR}${model}${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}${SEPARATOR}${model}${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}${SEPARATOR}${model}${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}${SEPARATOR}${model}${SEPARATOR}${xid}`;
 }
 // =============================================================================
 // New Vocabulary-Based Functions
@@ -157,15 +157,15 @@ function buildCompositeKey(entity, fields, suffix) {
     return buildCompositeKey$1(entity, fields, suffix);
 }
 /**
- * Calculate the organizational unit from a parent reference
+ * 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 calculateOu$1(parent);
+    return calculateScope$1(parent);
 }
 /**
  * Auto-populate GSI index keys on an entity
@@ -173,7 +173,7 @@ function calculateOu(parent) {
  * 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
+ * - 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
@@ -185,7 +185,7 @@ function calculateOu(parent) {
  */
 function indexEntity(entity, suffix = "") {
     const indexes = getModelIndexes(entity.model);
-    // Cast through unknown to bridge the type gap between StorableEntity and IndexableEntity
+    // Cast through unknown to bridge the type gap between StorableEntity and IndexableModel
     return populateIndexKeys(entity, indexes, suffix);
 }
 
@@ -209,7 +209,7 @@ function calculateEntitySuffix(entity) {
 /**
  * Get a single entity by primary key
  */
-const getEntity = serviceHandler({
+const getEntity = fabricService({
     alias: "getEntity",
     description: "Get a single entity by primary key",
     input: {
@@ -231,7 +231,7 @@ const getEntity = 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
+ * 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, }) {
@@ -250,7 +250,7 @@ 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
+ * 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, }) {
@@ -272,7 +272,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 = serviceHandler({
+const deleteEntity = fabricService({
     alias: "deleteEntity",
     description: "Soft delete an entity (sets deletedAt timestamp)",
     input: {
@@ -309,7 +309,7 @@ const deleteEntity = serviceHandler({
  * Archive an entity by setting archivedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const archiveEntity = serviceHandler({
+const archiveEntity = fabricService({
     alias: "archiveEntity",
     description: "Archive an entity (sets archivedAt timestamp)",
     input: {
@@ -346,7 +346,7 @@ const archiveEntity = serviceHandler({
  * Hard delete an entity (permanently removes from table)
  * Use with caution - prefer deleteEntity for soft delete
  */
-const destroyEntity = serviceHandler({
+const destroyEntity = fabricService({
     alias: "destroyEntity",
     description: "Hard delete an entity (permanently removes from table)",
     input: {
@@ -409,16 +409,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, }) {
+async function queryByScope({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, }) {
     const suffix = calculateSuffix$1({ archived, deleted });
-    const keyValue = buildIndexOu(ou, model) + suffix;
-    return executeQuery(INDEX_OU, keyValue, {
+    const keyValue = buildIndexScope(scope, model) + suffix;
+    return executeQuery(INDEX_SCOPE, keyValue, {
         ascending,
         limit,
         startKey,
@@ -428,7 +428,7 @@ async function queryByOu({ archived = false, ascending = false, deleted = false,
  * Query a single entity by human-friendly alias
  * Uses indexAlias GSI
  */
-const queryByAlias = serviceHandler({
+const queryByAlias = fabricService({
     alias: "queryByAlias",
     description: "Query a single entity by human-friendly alias",
     input: {
@@ -446,16 +446,19 @@ const queryByAlias = 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$1({ 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,
         });
@@ -466,12 +469,12 @@ const queryByAlias = 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, }) {
+async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, scope, recordClass, startKey, }) {
     const suffix = calculateSuffix$1({ archived, deleted });
-    const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
+    const keyValue = buildIndexClass(scope, model, recordClass) + suffix;
     return executeQuery(INDEX_CLASS, keyValue, {
         ascending,
         limit,
@@ -482,12 +485,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, }) {
+async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, type, }) {
     const suffix = calculateSuffix$1({ archived, deleted });
-    const keyValue = buildIndexType(ou, model, type) + suffix;
+    const keyValue = buildIndexType(scope, model, type) + suffix;
     return executeQuery(INDEX_TYPE, keyValue, {
         ascending,
         limit,
@@ -498,7 +501,7 @@ async function queryByType({ archived = false, ascending = false, deleted = fals
  * Query a single entity by external ID
  * Uses indexXid GSI
  */
-const queryByXid = serviceHandler({
+const queryByXid = fabricService({
     alias: "queryByXid",
     description: "Query a single entity by external ID",
     input: {
@@ -515,17 +518,20 @@ const queryByXid = 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$1({ 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,
         });
@@ -565,8 +571,8 @@ function buildFilterObject(params) {
     const result = {
         model: params.model,
     };
-    if (params.ou !== undefined) {
-        result.ou = params.ou;
+    if (params.scope !== undefined) {
+        result.scope = params.scope;
     }
     if (params.filter) {
         Object.assign(result, params.filter);
@@ -636,14 +642,14 @@ function selectBestIndex(indexes, filterFields) {
  * specific query function (queryByOu, queryByAlias, etc.) to use.
  *
  * @example
- * // Uses indexOu (pk: ["ou", "model"])
- * const allMessages = await query({ model: "message", ou: `chat#${chatId}` });
+ * // Uses indexScope (pk: ["scope", "model"])
+ * const allMessages = await query({ model: "message", scope: `chat#${chatId}` });
  *
  * @example
- * // Uses indexAlias (pk: ["ou", "model", "alias"])
+ * // Uses indexAlias (pk: ["scope", "model", "alias"])
  * const byAlias = await query({
  *   model: "record",
- *   ou: "@",
+ *   scope: "@",
  *   filter: { alias: "my-record" },
  * });
  *
@@ -702,18 +708,18 @@ function generateIndexName(pk) {
 /**
  * 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;
@@ -725,7 +731,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,
@@ -755,15 +761,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);
@@ -785,7 +791,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,
@@ -801,27 +807,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);
@@ -839,14 +845,14 @@ 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);
 }
 
-export { INDEX_ALIAS, INDEX_CLASS, INDEX_OU, INDEX_TYPE, INDEX_XID, archiveEntity, buildCompositeKey, buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, deleteEntity, destroyEntity, exportEntities, exportEntitiesToJson, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, putEntity, query, queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, resetClient, seedEntities, seedEntityIfNotExists, updateEntity };
+export { INDEX_ALIAS, INDEX_CLASS, INDEX_SCOPE, INDEX_TYPE, INDEX_XID, archiveEntity, buildCompositeKey, buildIndexAlias, buildIndexClass, buildIndexScope, buildIndexType, buildIndexXid, calculateScope, deleteEntity, destroyEntity, exportEntities, exportEntitiesToJson, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, putEntity, query, queryByAlias, queryByClass, queryByScope, queryByType, queryByXid, resetClient, seedEntities, seedEntityIfNotExists, updateEntity };
 //# sourceMappingURL=index.js.map