@jaypie/dynamodb 0.0.1

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","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":["DynamoDBClient","DynamoDBDocumentClient","ConfigurationError","GetCommand","PutCommand","DeleteCommand","QueryCommand"],"mappings":"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"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,7 @@
+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 { archiveEntity, deleteEntity, destroyEntity, getEntity, putEntity, updateEntity, } from "./entities.js";
+export { buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, indexEntity, } from "./keyBuilders.js";
+export { queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, } from "./queries.js";
+export type { ArchiveEntityParams, DeleteEntityParams, GetEntityParams, PutEntityParams, UpdateEntityParams, } from "./entities.js";
+export type { BaseQueryOptions, DynamoClientConfig, FabricEntity, ParentReference, QueryByAliasParams, QueryByClassParams, QueryByOuParams, QueryByTypeParams, QueryByXidParams, QueryResult, } from "./types.js";

package/dist/cjs/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/cjs/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>;

package/dist/cjs/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * DynamoDB client configuration
+ */
+export interface DynamoClientConfig {
+    /** DynamoDB table name */
+    tableName: string;
+    /** Optional endpoint URL for local development (e.g., "http://127.0.0.1:8100") */
+    endpoint?: string;
+    /** AWS region (default: "us-east-1") */
+    region?: string;
+    /** Optional credentials for local development */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+/**
+ * Parent reference for calculating OU
+ */
+export interface ParentReference {
+    id: string;
+    model: string;
+}
+/**
+ * Base query options shared by all query functions
+ */
+export interface BaseQueryOptions {
+    /** Query archived entities instead of active ones */
+    archived?: boolean;
+    /** Whether to sort ascending (oldest first). Default: false (most recent first) */
+    ascending?: boolean;
+    /** Query deleted entities instead of active ones */
+    deleted?: boolean;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Pagination cursor from previous query */
+    startKey?: Record<string, unknown>;
+}
+/**
+ * Parameters for queryByOu
+ */
+export interface QueryByOuParams extends BaseQueryOptions {
+    /** The entity model name */
+    model: string;
+    /** The organizational unit (APEX or "{parent.model}#{parent.id}") */
+    ou: string;
+}
+/**
+ * Parameters for queryByAlias
+ */
+export interface QueryByAliasParams {
+    /** The human-friendly alias */
+    alias: string;
+    /** Query archived entities instead of active ones */
+    archived?: boolean;
+    /** Query deleted entities instead of active ones */
+    deleted?: boolean;
+    /** The entity model name */
+    model: string;
+    /** The organizational unit */
+    ou: string;
+}
+/**
+ * Parameters for queryByClass
+ */
+export interface QueryByClassParams extends BaseQueryOptions {
+    /** The entity model name */
+    model: string;
+    /** The organizational unit */
+    ou: string;
+    /** The category classification */
+    recordClass: string;
+}
+/**
+ * Parameters for queryByType
+ */
+export interface QueryByTypeParams extends BaseQueryOptions {
+    /** The entity model name */
+    model: string;
+    /** The organizational unit */
+    ou: string;
+    /** The type classification */
+    type: string;
+}
+/**
+ * Parameters for queryByXid
+ */
+export interface QueryByXidParams {
+    /** Query archived entities instead of active ones */
+    archived?: boolean;
+    /** Query deleted entities instead of active ones */
+    deleted?: boolean;
+    /** The entity model name */
+    model: string;
+    /** The organizational unit */
+    ou: string;
+    /** The external ID */
+    xid: string;
+}
+/**
+ * Result of a query operation
+ */
+export interface QueryResult<T = FabricEntity> {
+    /** Array of matching entities */
+    items: T[];
+    /** Pagination cursor for next page (undefined if no more results) */
+    lastEvaluatedKey?: Record<string, unknown>;
+}
+/**
+ * Base entity interface for DynamoDB single-table design
+ */
+export interface FabricEntity {
+    /** Partition key (e.g., "record", "message") */
+    model: string;
+    /** Sort key (UUID) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Organizational unit: APEX ("@") or "{parent.model}#{parent.id}" */
+    ou: string;
+    /** Timestamp for chronological ordering (Date.now()) */
+    sequence: number;
+    indexAlias?: string;
+    indexClass?: string;
+    indexOu?: string;
+    indexType?: string;
+    indexXid?: string;
+    /** Human-friendly slug/alias */
+    alias?: string;
+    /** Category classification */
+    class?: string;
+    /** Type classification */
+    type?: string;
+    /** External ID for integration with external systems */
+    xid?: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Archive timestamp (for inactive but preserved records) */
+    archivedAt?: string;
+    /** Soft-delete timestamp */
+    deletedAt?: string;
+}

package/dist/esm/client.d.ts

@@ -0,0 +1,27 @@
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import type { DynamoClientConfig } from "./types.js";
+/**
+ * Initialize the DynamoDB client
+ * Must be called once at application startup before using query functions
+ *
+ * @param config - Client configuration
+ */
+export declare function initClient(config: DynamoClientConfig): void;
+/**
+ * Get the initialized DynamoDB Document Client
+ * @throws ConfigurationError if client has not been initialized
+ */
+export declare function getDocClient(): DynamoDBDocumentClient;
+/**
+ * Get the configured table name
+ * @throws ConfigurationError if client has not been initialized
+ */
+export declare function getTableName(): string;
+/**
+ * Check if the client has been initialized
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Reset the client state (primarily for testing)
+ */
+export declare function resetClient(): void;

package/dist/esm/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const APEX = "@";
+export declare const SEPARATOR = "#";
+export declare const INDEX_ALIAS = "indexAlias";
+export declare const INDEX_CLASS = "indexClass";
+export declare const INDEX_OU = "indexOu";
+export declare const INDEX_TYPE = "indexType";
+export declare const INDEX_XID = "indexXid";
+export declare const ARCHIVED_SUFFIX = "#archived";
+export declare const DELETED_SUFFIX = "#deleted";

package/dist/esm/entities.d.ts

@@ -0,0 +1,71 @@
+import type { FabricEntity } from "./types.js";
+/**
+ * Parameters for getEntity
+ */
+export interface GetEntityParams {
+    /** Entity ID (sort key) */
+    id: string;
+    /** Entity model (partition key) */
+    model: string;
+}
+/**
+ * Parameters for putEntity
+ */
+export interface PutEntityParams<T extends FabricEntity> {
+    /** The entity to save */
+    entity: T;
+}
+/**
+ * Parameters for updateEntity
+ */
+export interface UpdateEntityParams<T extends FabricEntity> {
+    /** The entity with updated fields */
+    entity: T;
+}
+/**
+ * Parameters for deleteEntity (soft delete)
+ */
+export interface DeleteEntityParams {
+    /** Entity ID (sort key) */
+    id: string;
+    /** Entity model (partition key) */
+    model: string;
+}
+/**
+ * Parameters for archiveEntity
+ */
+export interface ArchiveEntityParams {
+    /** Entity ID (sort key) */
+    id: string;
+    /** Entity model (partition key) */
+    model: string;
+}
+/**
+ * Get a single entity by primary key
+ */
+export declare function getEntity<T extends FabricEntity = FabricEntity>(params: GetEntityParams): Promise<T | null>;
+/**
+ * Put (create or replace) an entity
+ * Auto-populates GSI index keys via indexEntity
+ */
+export declare function putEntity<T extends FabricEntity>(params: PutEntityParams<T>): Promise<T>;
+/**
+ * Update an existing entity
+ * Auto-populates GSI index keys and sets updatedAt
+ */
+export declare function updateEntity<T extends FabricEntity>(params: UpdateEntityParams<T>): Promise<T>;
+/**
+ * Soft delete an entity by setting deletedAt timestamp
+ * Re-indexes with appropriate suffix based on archived/deleted state
+ */
+export declare function deleteEntity(params: DeleteEntityParams): Promise<boolean>;
+/**
+ * Archive an entity by setting archivedAt timestamp
+ * Re-indexes with appropriate suffix based on archived/deleted state
+ */
+export declare function archiveEntity(params: ArchiveEntityParams): Promise<boolean>;
+/**
+ * Hard delete an entity (permanently removes from table)
+ * Use with caution - prefer deleteEntity for soft delete
+ */
+export declare function destroyEntity(params: DeleteEntityParams): Promise<boolean>;

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+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 { archiveEntity, deleteEntity, destroyEntity, getEntity, putEntity, updateEntity, } from "./entities.js";
+export { buildIndexAlias, buildIndexClass, buildIndexOu, buildIndexType, buildIndexXid, calculateOu, indexEntity, } from "./keyBuilders.js";
+export { queryByAlias, queryByClass, queryByOu, queryByType, queryByXid, } from "./queries.js";
+export type { ArchiveEntityParams, DeleteEntityParams, GetEntityParams, PutEntityParams, UpdateEntityParams, } from "./entities.js";
+export type { BaseQueryOptions, DynamoClientConfig, FabricEntity, ParentReference, QueryByAliasParams, QueryByClassParams, QueryByOuParams, QueryByTypeParams, QueryByXidParams, QueryResult, } from "./types.js";