@jaypie/dynamodb 0.0.1

package/dist/esm/index.js

@@ -0,0 +1,450 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, PutCommand, DeleteCommand, GetCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
+import { ConfigurationError } from '@jaypie/errors';
+
+const DEFAULT_REGION = "us-east-1";
+const LOCAL_CREDENTIALS = {
+    accessKeyId: "local",
+    secretAccessKey: "local",
+};
+// Module-level state
+let docClient = null;
+let tableName = null;
+/**
+ * Check if endpoint indicates local development mode
+ */
+function isLocalEndpoint(endpoint) {
+    if (!endpoint)
+        return false;
+    return endpoint.includes("127.0.0.1") || endpoint.includes("localhost");
+}
+/**
+ * Initialize the DynamoDB client
+ * Must be called once at application startup before using query functions
+ *
+ * @param config - Client configuration
+ */
+function initClient(config) {
+    const { endpoint, region = DEFAULT_REGION } = config;
+    // Auto-detect local mode and use dummy credentials
+    const credentials = config.credentials ??
+        (isLocalEndpoint(endpoint) ? LOCAL_CREDENTIALS : undefined);
+    const dynamoClient = new DynamoDBClient({
+        ...(credentials && { credentials }),
+        ...(endpoint && { endpoint }),
+        region,
+    });
+    docClient = DynamoDBDocumentClient.from(dynamoClient, {
+        marshallOptions: {
+            removeUndefinedValues: true,
+        },
+    });
+    tableName = config.tableName;
+}
+/**
+ * Get the initialized DynamoDB Document Client
+ * @throws ConfigurationError if client has not been initialized
+ */
+function getDocClient() {
+    if (!docClient) {
+        throw new ConfigurationError("DynamoDB client not initialized. Call initClient() first.");
+    }
+    return docClient;
+}
+/**
+ * Get the configured table name
+ * @throws ConfigurationError if client has not been initialized
+ */
+function getTableName() {
+    if (!tableName) {
+        throw new ConfigurationError("DynamoDB client not initialized. Call initClient() first.");
+    }
+    return tableName;
+}
+/**
+ * Check if the client has been initialized
+ */
+function isInitialized() {
+    return docClient !== null && tableName !== null;
+}
+/**
+ * Reset the client state (primarily for testing)
+ */
+function resetClient() {
+    docClient = null;
+    tableName = null;
+}
+
+// Primary markers
+const APEX = "@"; // Root-level marker (DynamoDB prohibits empty strings)
+const SEPARATOR = "#"; // Composite key separator
+// GSI names
+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";
+
+/**
+ * Build the indexOu key for hierarchical queries
+ * @param ou - The organizational unit (APEX or "{parent.model}#{parent.id}")
+ * @param model - The entity model name
+ * @returns Composite key: "{ou}#{model}"
+ */
+function buildIndexOu(ou, model) {
+    return `${ou}${SEPARATOR}${model}`;
+}
+/**
+ * Build the indexAlias key for human-friendly lookups
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param alias - The human-friendly alias
+ * @returns Composite key: "{ou}#{model}#{alias}"
+ */
+function buildIndexAlias(ou, model, alias) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;
+}
+/**
+ * Build the indexClass key for category filtering
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param recordClass - The category classification
+ * @returns Composite key: "{ou}#{model}#{class}"
+ */
+function buildIndexClass(ou, model, recordClass) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
+}
+/**
+ * Build the indexType key for type filtering
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param type - The type classification
+ * @returns Composite key: "{ou}#{model}#{type}"
+ */
+function buildIndexType(ou, model, type) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;
+}
+/**
+ * Build the indexXid key for external ID lookups
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param xid - The external ID
+ * @returns Composite key: "{ou}#{model}#{xid}"
+ */
+function buildIndexXid(ou, model, xid) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+}
+/**
+ * Calculate the organizational unit from a parent reference
+ * @param parent - Optional parent entity reference
+ * @returns APEX ("@") if no parent, otherwise "{parent.model}#{parent.id}"
+ */
+function calculateOu(parent) {
+    if (!parent) {
+        return APEX;
+    }
+    return `${parent.model}${SEPARATOR}${parent.id}`;
+}
+/**
+ * Auto-populate GSI index keys on an entity
+ * - indexOu is always populated from ou + 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
+ * - indexXid is populated only when xid is present
+ *
+ * @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
+ */
+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;
+}
+
+/**
+ * Get a single entity by primary key
+ */
+async function getEntity(params) {
+    const { id, model } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    const command = new GetCommand({
+        Key: { id, model },
+        TableName: tableName,
+    });
+    const response = await docClient.send(command);
+    return response.Item ?? null;
+}
+/**
+ * Put (create or replace) an entity
+ * Auto-populates GSI index keys via indexEntity
+ */
+async function putEntity(params) {
+    const { entity } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Auto-populate index keys
+    const indexedEntity = indexEntity(entity);
+    const command = new PutCommand({
+        Item: indexedEntity,
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return indexedEntity;
+}
+/**
+ * Update an existing entity
+ * Auto-populates GSI index keys and sets updatedAt
+ */
+async function updateEntity(params) {
+    const { entity } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Update timestamp and re-index
+    const updatedEntity = indexEntity({
+        ...entity,
+        updatedAt: new Date().toISOString(),
+    });
+    const command = new PutCommand({
+        Item: updatedEntity,
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return updatedEntity;
+}
+/**
+ * Calculate suffix based on entity's archived/deleted state
+ */
+function calculateEntitySuffix(entity) {
+    const hasArchived = Boolean(entity.archivedAt);
+    const hasDeleted = Boolean(entity.deletedAt);
+    if (hasArchived && hasDeleted) {
+        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+    }
+    if (hasArchived) {
+        return ARCHIVED_SUFFIX;
+    }
+    if (hasDeleted) {
+        return DELETED_SUFFIX;
+    }
+    return "";
+}
+/**
+ * Soft delete an entity by setting deletedAt timestamp
+ * Re-indexes with appropriate suffix based on archived/deleted state
+ */
+async function deleteEntity(params) {
+    const { id, model } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Fetch the current entity
+    const existing = await getEntity({ id, model });
+    if (!existing) {
+        return false;
+    }
+    const now = new Date().toISOString();
+    // Build updated entity with deletedAt
+    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({
+        Item: deletedEntity,
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return true;
+}
+/**
+ * Archive an entity by setting archivedAt timestamp
+ * Re-indexes with appropriate suffix based on archived/deleted state
+ */
+async function archiveEntity(params) {
+    const { id, model } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Fetch the current entity
+    const existing = await getEntity({ id, model });
+    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({
+        Item: archivedEntity,
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return true;
+}
+/**
+ * Hard delete an entity (permanently removes from table)
+ * Use with caution - prefer deleteEntity for soft delete
+ */
+async function destroyEntity(params) {
+    const { id, model } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    const command = new DeleteCommand({
+        Key: { id, model },
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return true;
+}
+
+/**
+ * Calculate the suffix based on archived/deleted flags
+ * When both are true, returns combined suffix (archived first, alphabetically)
+ */
+function calculateSuffix({ archived, deleted, }) {
+    if (archived && deleted) {
+        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+    }
+    if (archived) {
+        return ARCHIVED_SUFFIX;
+    }
+    if (deleted) {
+        return DELETED_SUFFIX;
+    }
+    return "";
+}
+/**
+ * Execute a GSI query with common options
+ */
+async function executeQuery(indexName, keyValue, options = {}) {
+    const { ascending = false, limit, startKey } = options;
+    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 response = await docClient.send(command);
+    return {
+        items: (response.Items ?? []),
+        lastEvaluatedKey: response.LastEvaluatedKey,
+    };
+}
+/**
+ * Query entities by organizational unit (parent hierarchy)
+ * Uses indexOu GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ */
+async function queryByOu(params) {
+    const { archived, deleted, model, ou, ...options } = params;
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexOu(ou, model) + suffix;
+    return executeQuery(INDEX_OU, keyValue, options);
+}
+/**
+ * Query a single entity by human-friendly alias
+ * Uses indexAlias GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ * @returns The matching entity or null if not found
+ */
+async function queryByAlias(params) {
+    const { alias, archived, deleted, model, ou } = params;
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexAlias(ou, model, alias) + suffix;
+    const result = await executeQuery(INDEX_ALIAS, keyValue, { limit: 1 });
+    return result.items[0] ?? null;
+}
+/**
+ * Query entities by category classification
+ * Uses indexClass GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ */
+async function queryByClass(params) {
+    const { archived, deleted, model, ou, recordClass, ...options } = params;
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
+    return executeQuery(INDEX_CLASS, keyValue, options);
+}
+/**
+ * Query entities by type classification
+ * Uses indexType GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ */
+async function queryByType(params) {
+    const { archived, deleted, model, ou, type, ...options } = params;
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexType(ou, model, type) + suffix;
+    return executeQuery(INDEX_TYPE, keyValue, options);
+}
+/**
+ * Query a single entity by external ID
+ * Uses indexXid GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ * @returns The matching entity or null if not found
+ */
+async function queryByXid(params) {
+    const { archived, deleted, model, ou, xid } = params;
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexXid(ou, model, xid) + suffix;
+    const result = await executeQuery(INDEX_XID, keyValue, { limit: 1 });
+    return result.items[0] ?? null;
+}
+
+export { APEX, ARCHIVED_SUFFIX, DELETED_SUFFIX, INDEX_ALIAS, INDEX_CLASS, INDEX_OU, INDEX_TYPE, INDEX_XID, SEPARATOR, archiveEntity, buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, deleteEntity, destroyEntity, getDocClient, getEntity, getTableName, indexEntity, initClient, isInitialized, putEntity, queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, resetClient, updateEntity };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/client.ts","../../../src/constants.ts","../../../src/keyBuilders.ts","../../../src/entities.ts","../../../src/queries.ts"],"sourcesContent":["import { DynamoDBClient } from \"@aws-sdk/client-dynamodb\";\nimport { DynamoDBDocumentClient } from \"@aws-sdk/lib-dynamodb\";\nimport { ConfigurationError } from \"@jaypie/errors\";\n\nimport type { DynamoClientConfig } from \"./types.js\";\n\nconst DEFAULT_REGION = \"us-east-1\";\nconst LOCAL_CREDENTIALS = {\n  accessKeyId: \"local\",\n  secretAccessKey: \"local\",\n};\n\n// Module-level state\nlet docClient: DynamoDBDocumentClient | null = null;\nlet tableName: string | null = null;\n\n/**\n * Check if endpoint indicates local development mode\n */\nfunction isLocalEndpoint(endpoint?: string): boolean {\n  if (!endpoint) return false;\n  return endpoint.includes(\"127.0.0.1\") || endpoint.includes(\"localhost\");\n}\n\n/**\n * Initialize the DynamoDB client\n * Must be called once at application startup before using query functions\n *\n * @param config - Client configuration\n */\nexport function initClient(config: DynamoClientConfig): void {\n  const { endpoint, region = DEFAULT_REGION } = config;\n\n  // Auto-detect local mode and use dummy credentials\n  const credentials =\n    config.credentials ??\n    (isLocalEndpoint(endpoint) ? LOCAL_CREDENTIALS : undefined);\n\n  const dynamoClient = new DynamoDBClient({\n    ...(credentials && { credentials }),\n    ...(endpoint && { endpoint }),\n    region,\n  });\n\n  docClient = DynamoDBDocumentClient.from(dynamoClient, {\n    marshallOptions: {\n      removeUndefinedValues: true,\n    },\n  });\n\n  tableName = config.tableName;\n}\n\n/**\n * Get the initialized DynamoDB Document Client\n * @throws ConfigurationError if client has not been initialized\n */\nexport function getDocClient(): DynamoDBDocumentClient {\n  if (!docClient) {\n    throw new ConfigurationError(\n      \"DynamoDB client not initialized. Call initClient() first.\",\n    );\n  }\n  return docClient;\n}\n\n/**\n * Get the configured table name\n * @throws ConfigurationError if client has not been initialized\n */\nexport function getTableName(): string {\n  if (!tableName) {\n    throw new ConfigurationError(\n      \"DynamoDB client not initialized. Call initClient() first.\",\n    );\n  }\n  return tableName;\n}\n\n/**\n * Check if the client has been initialized\n */\nexport function isInitialized(): boolean {\n  return docClient !== null && tableName !== null;\n}\n\n/**\n * Reset the client state (primarily for testing)\n */\nexport function resetClient(): void {\n  docClient = null;\n  tableName = null;\n}\n","// Primary markers\nexport const APEX = \"@\"; // Root-level marker (DynamoDB prohibits empty strings)\nexport const SEPARATOR = \"#\"; // Composite key separator\n\n// GSI names\nexport const INDEX_ALIAS = \"indexAlias\";\nexport const INDEX_CLASS = \"indexClass\";\nexport const INDEX_OU = \"indexOu\";\nexport const INDEX_TYPE = \"indexType\";\nexport const INDEX_XID = \"indexXid\";\n\n// Index suffixes for soft state\nexport const ARCHIVED_SUFFIX = \"#archived\";\nexport const DELETED_SUFFIX = \"#deleted\";\n","import { APEX, SEPARATOR } from \"./constants.js\";\nimport type { FabricEntity, ParentReference } from \"./types.js\";\n\n/**\n * Build the indexOu key for hierarchical queries\n * @param ou - The organizational unit (APEX or \"{parent.model}#{parent.id}\")\n * @param model - The entity model name\n * @returns Composite key: \"{ou}#{model}\"\n */\nexport function buildIndexOu(ou: string, model: string): string {\n  return `${ou}${SEPARATOR}${model}`;\n}\n\n/**\n * Build the indexAlias key for human-friendly lookups\n * @param ou - The organizational unit\n * @param model - The entity model name\n * @param alias - The human-friendly alias\n * @returns Composite key: \"{ou}#{model}#{alias}\"\n */\nexport function buildIndexAlias(\n  ou: string,\n  model: string,\n  alias: string,\n): string {\n  return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;\n}\n\n/**\n * Build the indexClass key for category filtering\n * @param ou - The organizational unit\n * @param model - The entity model name\n * @param recordClass - The category classification\n * @returns Composite key: \"{ou}#{model}#{class}\"\n */\nexport function buildIndexClass(\n  ou: string,\n  model: string,\n  recordClass: string,\n): string {\n  return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;\n}\n\n/**\n * Build the indexType key for type filtering\n * @param ou - The organizational unit\n * @param model - The entity model name\n * @param type - The type classification\n * @returns Composite key: \"{ou}#{model}#{type}\"\n */\nexport function buildIndexType(\n  ou: string,\n  model: string,\n  type: string,\n): string {\n  return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;\n}\n\n/**\n * Build the indexXid key for external ID lookups\n * @param ou - The organizational unit\n * @param model - The entity model name\n * @param xid - The external ID\n * @returns Composite key: \"{ou}#{model}#{xid}\"\n */\nexport function buildIndexXid(ou: string, model: string, xid: string): string {\n  return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;\n}\n\n/**\n * Calculate the organizational unit from a parent reference\n * @param parent - Optional parent entity reference\n * @returns APEX (\"@\") if no parent, otherwise \"{parent.model}#{parent.id}\"\n */\nexport function calculateOu(parent?: ParentReference): string {\n  if (!parent) {\n    return APEX;\n  }\n  return `${parent.model}${SEPARATOR}${parent.id}`;\n}\n\n/**\n * Auto-populate GSI index keys on an entity\n * - indexOu is always populated from ou + model\n * - indexAlias is populated only when alias is present\n * - indexClass is populated only when class is present\n * - indexType is populated only when type is present\n * - indexXid is populated only when xid is present\n *\n * @param entity - The entity to populate index keys for\n * @param suffix - Optional suffix to append to all index keys (e.g., \"#deleted\", \"#archived\")\n * @returns The entity with populated index keys\n */\nexport function indexEntity<T extends FabricEntity>(\n  entity: T,\n  suffix: string = \"\",\n): T {\n  const result = { ...entity };\n\n  // indexOu is always set (from ou + model)\n  result.indexOu = buildIndexOu(entity.ou, entity.model) + suffix;\n\n  // Optional indexes - only set when the source field is present\n  if (entity.alias !== undefined) {\n    result.indexAlias =\n      buildIndexAlias(entity.ou, entity.model, entity.alias) + suffix;\n  }\n\n  if (entity.class !== undefined) {\n    result.indexClass =\n      buildIndexClass(entity.ou, entity.model, entity.class) + suffix;\n  }\n\n  if (entity.type !== undefined) {\n    result.indexType =\n      buildIndexType(entity.ou, entity.model, entity.type) + suffix;\n  }\n\n  if (entity.xid !== undefined) {\n    result.indexXid =\n      buildIndexXid(entity.ou, entity.model, entity.xid) + suffix;\n  }\n\n  return result;\n}\n","import { DeleteCommand, GetCommand, PutCommand } from \"@aws-sdk/lib-dynamodb\";\n\nimport { getDocClient, getTableName } from \"./client.js\";\nimport { ARCHIVED_SUFFIX, DELETED_SUFFIX } from \"./constants.js\";\nimport { indexEntity } from \"./keyBuilders.js\";\nimport type { FabricEntity } from \"./types.js\";\n\n/**\n * Parameters for getEntity\n */\nexport interface GetEntityParams {\n  /** Entity ID (sort key) */\n  id: string;\n  /** Entity model (partition key) */\n  model: string;\n}\n\n/**\n * Parameters for putEntity\n */\nexport interface PutEntityParams<T extends FabricEntity> {\n  /** The entity to save */\n  entity: T;\n}\n\n/**\n * Parameters for updateEntity\n */\nexport interface UpdateEntityParams<T extends FabricEntity> {\n  /** The entity with updated fields */\n  entity: T;\n}\n\n/**\n * Parameters for deleteEntity (soft delete)\n */\nexport interface DeleteEntityParams {\n  /** Entity ID (sort key) */\n  id: string;\n  /** Entity model (partition key) */\n  model: string;\n}\n\n/**\n * Parameters for archiveEntity\n */\nexport interface ArchiveEntityParams {\n  /** Entity ID (sort key) */\n  id: string;\n  /** Entity model (partition key) */\n  model: string;\n}\n\n/**\n * Get a single entity by primary key\n */\nexport async function getEntity<T extends FabricEntity = FabricEntity>(\n  params: GetEntityParams,\n): Promise<T | null> {\n  const { id, model } = params;\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  const command = new GetCommand({\n    Key: { id, model },\n    TableName: tableName,\n  });\n\n  const response = await docClient.send(command);\n  return (response.Item as T) ?? null;\n}\n\n/**\n * Put (create or replace) an entity\n * Auto-populates GSI index keys via indexEntity\n */\nexport async function putEntity<T extends FabricEntity>(\n  params: PutEntityParams<T>,\n): Promise<T> {\n  const { entity } = params;\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  // Auto-populate index keys\n  const indexedEntity = indexEntity(entity);\n\n  const command = new PutCommand({\n    Item: indexedEntity,\n    TableName: tableName,\n  });\n\n  await docClient.send(command);\n  return indexedEntity;\n}\n\n/**\n * Update an existing entity\n * Auto-populates GSI index keys and sets updatedAt\n */\nexport async function updateEntity<T extends FabricEntity>(\n  params: UpdateEntityParams<T>,\n): Promise<T> {\n  const { entity } = params;\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  // Update timestamp and re-index\n  const updatedEntity = indexEntity({\n    ...entity,\n    updatedAt: new Date().toISOString(),\n  });\n\n  const command = new PutCommand({\n    Item: updatedEntity,\n    TableName: tableName,\n  });\n\n  await docClient.send(command);\n  return updatedEntity;\n}\n\n/**\n * Calculate suffix based on entity's archived/deleted state\n */\nfunction calculateEntitySuffix(entity: {\n  archivedAt?: string;\n  deletedAt?: string;\n}): string {\n  const hasArchived = Boolean(entity.archivedAt);\n  const hasDeleted = Boolean(entity.deletedAt);\n\n  if (hasArchived && hasDeleted) {\n    return ARCHIVED_SUFFIX + DELETED_SUFFIX;\n  }\n  if (hasArchived) {\n    return ARCHIVED_SUFFIX;\n  }\n  if (hasDeleted) {\n    return DELETED_SUFFIX;\n  }\n  return \"\";\n}\n\n/**\n * Soft delete an entity by setting deletedAt timestamp\n * Re-indexes with appropriate suffix based on archived/deleted state\n */\nexport async function deleteEntity(\n  params: DeleteEntityParams,\n): Promise<boolean> {\n  const { id, model } = params;\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  // Fetch the current entity\n  const existing = await getEntity({ id, model });\n  if (!existing) {\n    return false;\n  }\n\n  const now = new Date().toISOString();\n\n  // Build updated entity with deletedAt\n  const updatedEntity = {\n    ...existing,\n    deletedAt: now,\n    updatedAt: now,\n  };\n\n  // Calculate suffix based on combined state (may already be archived)\n  const suffix = calculateEntitySuffix(updatedEntity);\n  const deletedEntity = indexEntity(updatedEntity, suffix);\n\n  const command = new PutCommand({\n    Item: deletedEntity,\n    TableName: tableName,\n  });\n\n  await docClient.send(command);\n  return true;\n}\n\n/**\n * Archive an entity by setting archivedAt timestamp\n * Re-indexes with appropriate suffix based on archived/deleted state\n */\nexport async function archiveEntity(\n  params: ArchiveEntityParams,\n): Promise<boolean> {\n  const { id, model } = params;\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  // Fetch the current entity\n  const existing = await getEntity({ id, model });\n  if (!existing) {\n    return false;\n  }\n\n  const now = new Date().toISOString();\n\n  // Build updated entity with archivedAt\n  const updatedEntity = {\n    ...existing,\n    archivedAt: now,\n    updatedAt: now,\n  };\n\n  // Calculate suffix based on combined state (may already be deleted)\n  const suffix = calculateEntitySuffix(updatedEntity);\n  const archivedEntity = indexEntity(updatedEntity, suffix);\n\n  const command = new PutCommand({\n    Item: archivedEntity,\n    TableName: tableName,\n  });\n\n  await docClient.send(command);\n  return true;\n}\n\n/**\n * Hard delete an entity (permanently removes from table)\n * Use with caution - prefer deleteEntity for soft delete\n */\nexport async function destroyEntity(\n  params: DeleteEntityParams,\n): Promise<boolean> {\n  const { id, model } = params;\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  const command = new DeleteCommand({\n    Key: { id, model },\n    TableName: tableName,\n  });\n\n  await docClient.send(command);\n  return true;\n}\n","import { QueryCommand } from \"@aws-sdk/lib-dynamodb\";\n\nimport { getDocClient, getTableName } from \"./client.js\";\nimport {\n  ARCHIVED_SUFFIX,\n  DELETED_SUFFIX,\n  INDEX_ALIAS,\n  INDEX_CLASS,\n  INDEX_OU,\n  INDEX_TYPE,\n  INDEX_XID,\n} from \"./constants.js\";\nimport {\n  buildIndexAlias,\n  buildIndexClass,\n  buildIndexOu,\n  buildIndexType,\n  buildIndexXid,\n} from \"./keyBuilders.js\";\nimport type {\n  BaseQueryOptions,\n  FabricEntity,\n  QueryByAliasParams,\n  QueryByClassParams,\n  QueryByOuParams,\n  QueryByTypeParams,\n  QueryByXidParams,\n  QueryResult,\n} from \"./types.js\";\n\n/**\n * Calculate the suffix based on archived/deleted flags\n * When both are true, returns combined suffix (archived first, alphabetically)\n */\nfunction calculateSuffix({\n  archived,\n  deleted,\n}: {\n  archived?: boolean;\n  deleted?: boolean;\n}): string {\n  if (archived && deleted) {\n    return ARCHIVED_SUFFIX + DELETED_SUFFIX;\n  }\n  if (archived) {\n    return ARCHIVED_SUFFIX;\n  }\n  if (deleted) {\n    return DELETED_SUFFIX;\n  }\n  return \"\";\n}\n\n/**\n * Execute a GSI query with common options\n */\nasync function executeQuery<T extends FabricEntity>(\n  indexName: string,\n  keyValue: string,\n  options: BaseQueryOptions = {},\n): Promise<QueryResult<T>> {\n  const { ascending = false, limit, startKey } = options;\n\n  const docClient = getDocClient();\n  const tableName = getTableName();\n\n  const command = new QueryCommand({\n    ExclusiveStartKey: startKey as Record<string, unknown> | undefined,\n    ExpressionAttributeNames: {\n      \"#pk\": indexName,\n    },\n    ExpressionAttributeValues: {\n      \":pkValue\": keyValue,\n    },\n    IndexName: indexName,\n    KeyConditionExpression: \"#pk = :pkValue\",\n    ...(limit && { Limit: limit }),\n    ScanIndexForward: ascending,\n    TableName: tableName,\n  });\n\n  const response = await docClient.send(command);\n\n  return {\n    items: (response.Items ?? []) as T[],\n    lastEvaluatedKey: response.LastEvaluatedKey,\n  };\n}\n\n/**\n * Query entities by organizational unit (parent hierarchy)\n * Uses indexOu GSI\n *\n * @param params.archived - Query archived entities instead of active ones\n * @param params.deleted - Query deleted entities instead of active ones\n * @throws ConfigurationError if both archived and deleted are true\n */\nexport async function queryByOu<T extends FabricEntity = FabricEntity>(\n  params: QueryByOuParams,\n): Promise<QueryResult<T>> {\n  const { archived, deleted, model, ou, ...options } = params;\n  const suffix = calculateSuffix({ archived, deleted });\n  const keyValue = buildIndexOu(ou, model) + suffix;\n  return executeQuery<T>(INDEX_OU, keyValue, options);\n}\n\n/**\n * Query a single entity by human-friendly alias\n * Uses indexAlias GSI\n *\n * @param params.archived - Query archived entities instead of active ones\n * @param params.deleted - Query deleted entities instead of active ones\n * @throws ConfigurationError if both archived and deleted are true\n * @returns The matching entity or null if not found\n */\nexport async function queryByAlias<T extends FabricEntity = FabricEntity>(\n  params: QueryByAliasParams,\n): Promise<T | null> {\n  const { alias, archived, deleted, model, ou } = params;\n  const suffix = calculateSuffix({ archived, deleted });\n  const keyValue = buildIndexAlias(ou, model, alias) + suffix;\n  const result = await executeQuery<T>(INDEX_ALIAS, keyValue, { limit: 1 });\n  return result.items[0] ?? null;\n}\n\n/**\n * Query entities by category classification\n * Uses indexClass GSI\n *\n * @param params.archived - Query archived entities instead of active ones\n * @param params.deleted - Query deleted entities instead of active ones\n * @throws ConfigurationError if both archived and deleted are true\n */\nexport async function queryByClass<T extends FabricEntity = FabricEntity>(\n  params: QueryByClassParams,\n): Promise<QueryResult<T>> {\n  const { archived, deleted, model, ou, recordClass, ...options } = params;\n  const suffix = calculateSuffix({ archived, deleted });\n  const keyValue = buildIndexClass(ou, model, recordClass) + suffix;\n  return executeQuery<T>(INDEX_CLASS, keyValue, options);\n}\n\n/**\n * Query entities by type classification\n * Uses indexType GSI\n *\n * @param params.archived - Query archived entities instead of active ones\n * @param params.deleted - Query deleted entities instead of active ones\n * @throws ConfigurationError if both archived and deleted are true\n */\nexport async function queryByType<T extends FabricEntity = FabricEntity>(\n  params: QueryByTypeParams,\n): Promise<QueryResult<T>> {\n  const { archived, deleted, model, ou, type, ...options } = params;\n  const suffix = calculateSuffix({ archived, deleted });\n  const keyValue = buildIndexType(ou, model, type) + suffix;\n  return executeQuery<T>(INDEX_TYPE, keyValue, options);\n}\n\n/**\n * Query a single entity by external ID\n * Uses indexXid GSI\n *\n * @param params.archived - Query archived entities instead of active ones\n * @param params.deleted - Query deleted entities instead of active ones\n * @throws ConfigurationError if both archived and deleted are true\n * @returns The matching entity or null if not found\n */\nexport async function queryByXid<T extends FabricEntity = FabricEntity>(\n  params: QueryByXidParams,\n): Promise<T | null> {\n  const { archived, deleted, model, ou, xid } = params;\n  const suffix = calculateSuffix({ archived, deleted });\n  const keyValue = buildIndexXid(ou, model, xid) + suffix;\n  const result = await executeQuery<T>(INDEX_XID, keyValue, { limit: 1 });\n  return result.items[0] ?? null;\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/keyBuilders.d.ts

@@ -0,0 +1,59 @@
+import type { FabricEntity, ParentReference } from "./types.js";
+/**
+ * Build the indexOu key for hierarchical queries
+ * @param ou - The organizational unit (APEX or "{parent.model}#{parent.id}")
+ * @param model - The entity model name
+ * @returns Composite key: "{ou}#{model}"
+ */
+export declare function buildIndexOu(ou: string, model: string): string;
+/**
+ * Build the indexAlias key for human-friendly lookups
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param alias - The human-friendly alias
+ * @returns Composite key: "{ou}#{model}#{alias}"
+ */
+export declare function buildIndexAlias(ou: string, model: string, alias: string): string;
+/**
+ * Build the indexClass key for category filtering
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param recordClass - The category classification
+ * @returns Composite key: "{ou}#{model}#{class}"
+ */
+export declare function buildIndexClass(ou: string, model: string, recordClass: string): string;
+/**
+ * Build the indexType key for type filtering
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param type - The type classification
+ * @returns Composite key: "{ou}#{model}#{type}"
+ */
+export declare function buildIndexType(ou: string, model: string, type: string): string;
+/**
+ * Build the indexXid key for external ID lookups
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param xid - The external ID
+ * @returns Composite key: "{ou}#{model}#{xid}"
+ */
+export declare function buildIndexXid(ou: string, model: string, xid: string): string;
+/**
+ * Calculate the organizational unit from a parent reference
+ * @param parent - Optional parent entity reference
+ * @returns APEX ("@") if no parent, otherwise "{parent.model}#{parent.id}"
+ */
+export declare function calculateOu(parent?: ParentReference): string;
+/**
+ * Auto-populate GSI index keys on an entity
+ * - indexOu is always populated from ou + 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
+ * - indexXid is populated only when xid is present
+ *
+ * @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
+ */
+export declare function indexEntity<T extends FabricEntity>(entity: T, suffix?: string): T;

package/dist/esm/queries.d.ts

@@ -0,0 +1,48 @@
+import type { FabricEntity, QueryByAliasParams, QueryByClassParams, QueryByOuParams, QueryByTypeParams, QueryByXidParams, QueryResult } from "./types.js";
+/**
+ * Query entities by organizational unit (parent hierarchy)
+ * Uses indexOu GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ */
+export declare function queryByOu<T extends FabricEntity = FabricEntity>(params: QueryByOuParams): Promise<QueryResult<T>>;
+/**
+ * Query a single entity by human-friendly alias
+ * Uses indexAlias GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ * @returns The matching entity or null if not found
+ */
+export declare function queryByAlias<T extends FabricEntity = FabricEntity>(params: QueryByAliasParams): Promise<T | null>;
+/**
+ * Query entities by category classification
+ * Uses indexClass GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ */
+export declare function queryByClass<T extends FabricEntity = FabricEntity>(params: QueryByClassParams): Promise<QueryResult<T>>;
+/**
+ * Query entities by type classification
+ * Uses indexType GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ */
+export declare function queryByType<T extends FabricEntity = FabricEntity>(params: QueryByTypeParams): Promise<QueryResult<T>>;
+/**
+ * Query a single entity by external ID
+ * Uses indexXid GSI
+ *
+ * @param params.archived - Query archived entities instead of active ones
+ * @param params.deleted - Query deleted entities instead of active ones
+ * @throws ConfigurationError if both archived and deleted are true
+ * @returns The matching entity or null if not found
+ */
+export declare function queryByXid<T extends FabricEntity = FabricEntity>(params: QueryByXidParams): Promise<T | null>;