@jaypie/dynamodb 0.1.0 → 0.1.2

package/dist/cjs/client.d.ts

@@ -6,7 +6,7 @@ import type { DynamoClientConfig } from "./types.js";
  *
  * @param config - Client configuration
  */
-export declare function initClient(config: DynamoClientConfig): void;
+export declare function initClient(config?: DynamoClientConfig): void;
 /**
  * Get the initialized DynamoDB Document Client
  * @throws ConfigurationError if client has not been initialized

package/dist/cjs/entities.d.ts

@@ -1,71 +1,40 @@
 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>;
+export declare const getEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, FabricEntity | null>;
 /**
  * Put (create or replace) an entity
  * Auto-populates GSI index keys via indexEntity
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex FabricEntity objects that can't be coerced by vocabulary's type system.
  */
-export declare function putEntity<T extends FabricEntity>(params: PutEntityParams<T>): Promise<T>;
+export declare function putEntity({ entity, }: {
+    entity: FabricEntity;
+}): Promise<FabricEntity>;
 /**
  * Update an existing entity
  * Auto-populates GSI index keys and sets updatedAt
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex FabricEntity objects that can't be coerced by vocabulary's type system.
  */
-export declare function updateEntity<T extends FabricEntity>(params: UpdateEntityParams<T>): Promise<T>;
+export declare function updateEntity({ entity, }: {
+    entity: FabricEntity;
+}): Promise<FabricEntity>;
 /**
  * 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>;
+export declare const deleteEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, 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>;
+export declare const archiveEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, 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>;
+export declare const destroyEntity: import("@jaypie/vocabulary").ServiceHandlerFunction<Record<string, unknown>, boolean>;

package/dist/cjs/index.cjs

@@ -3,7 +3,12 @@
 var clientDynamodb = require('@aws-sdk/client-dynamodb');
 var libDynamodb = require('@aws-sdk/lib-dynamodb');
 var errors = require('@jaypie/errors');
+var vocabulary = require('@jaypie/vocabulary');
 
+// Environment variable names
+const ENV_AWS_REGION = "AWS_REGION";
+const ENV_DYNAMODB_TABLE_NAME = "DYNAMODB_TABLE_NAME";
+// Defaults
 const DEFAULT_REGION = "us-east-1";
 const LOCAL_CREDENTIALS = {
     accessKeyId: "local",
@@ -26,8 +31,9 @@ function isLocalEndpoint(endpoint) {
  *
  * @param config - Client configuration
  */
-function initClient(config) {
-    const { endpoint, region = DEFAULT_REGION } = config;
+function initClient(config = {}) {
+    const { endpoint } = config;
+    const region = config.region ?? process.env[ENV_AWS_REGION] ?? DEFAULT_REGION;
     // Auto-detect local mode and use dummy credentials
     const credentials = config.credentials ??
         (isLocalEndpoint(endpoint) ? LOCAL_CREDENTIALS : undefined);
@@ -41,7 +47,7 @@ function initClient(config) {
             removeUndefinedValues: true,
         },
     });
-    tableName = config.tableName;
+    tableName = config.tableName ?? process.env[ENV_DYNAMODB_TABLE_NAME] ?? null;
 }
 /**
  * Get the initialized DynamoDB Document Client
@@ -187,25 +193,51 @@ function indexEntity(entity, suffix = "") {
 }
 
 /**
- * Get a single entity by primary key
+ * Calculate suffix based on entity's archived/deleted state
  */
-async function getEntity(params) {
-    const { id, model } = params;
-    const docClient = getDocClient();
-    const tableName = getTableName();
-    const command = new libDynamodb.GetCommand({
-        Key: { id, model },
-        TableName: tableName,
-    });
-    const response = await docClient.send(command);
-    return response.Item ?? null;
+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 "";
 }
+/**
+ * Get a single entity by primary key
+ */
+const getEntity = vocabulary.serviceHandler({
+    alias: "getEntity",
+    description: "Get a single entity by primary key",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        const docClient = getDocClient();
+        const tableName = getTableName();
+        const command = new libDynamodb.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
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex FabricEntity objects that can't be coerced by vocabulary's type system.
  */
-async function putEntity(params) {
-    const { entity } = params;
+async function putEntity({ entity, }) {
     const docClient = getDocClient();
     const tableName = getTableName();
     // Auto-populate index keys
@@ -220,9 +252,11 @@ async function putEntity(params) {
 /**
  * Update an existing entity
  * Auto-populates GSI index keys and sets updatedAt
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex FabricEntity objects that can't be coerced by vocabulary's type system.
  */
-async function updateEntity(params) {
-    const { entity } = params;
+async function updateEntity({ entity, }) {
     const docClient = getDocClient();
     const tableName = getTableName();
     // Update timestamp and re-index
@@ -237,98 +271,102 @@ async function updateEntity(params) {
     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 libDynamodb.PutCommand({
-        Item: deletedEntity,
-        TableName: tableName,
-    });
-    await docClient.send(command);
-    return true;
-}
+const deleteEntity = vocabulary.serviceHandler({
+    alias: "deleteEntity",
+    description: "Soft delete an entity (sets deletedAt timestamp)",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        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 libDynamodb.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 libDynamodb.PutCommand({
-        Item: archivedEntity,
-        TableName: tableName,
-    });
-    await docClient.send(command);
-    return true;
-}
+const archiveEntity = vocabulary.serviceHandler({
+    alias: "archiveEntity",
+    description: "Archive an entity (sets archivedAt timestamp)",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        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 libDynamodb.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 libDynamodb.DeleteCommand({
-        Key: { id, model },
-        TableName: tableName,
-    });
-    await docClient.send(command);
-    return true;
-}
+const destroyEntity = vocabulary.serviceHandler({
+    alias: "destroyEntity",
+    description: "Hard delete an entity (permanently removes from table)",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        const docClient = getDocClient();
+        const tableName = getTableName();
+        const command = new libDynamodb.DeleteCommand({
+            Key: { id, model },
+            TableName: tableName,
+        });
+        await docClient.send(command);
+        return true;
+    },
+});
 
 /**
  * Calculate the suffix based on archived/deleted flags
@@ -377,76 +415,126 @@ async function executeQuery(indexName, keyValue, options = {}) {
  * 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
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-async function queryByOu(params) {
-    const { archived, deleted, model, ou, ...options } = params;
+async function queryByOu({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, }) {
     const suffix = calculateSuffix({ archived, deleted });
     const keyValue = buildIndexOu(ou, model) + suffix;
-    return executeQuery(INDEX_OU, keyValue, options);
+    return executeQuery(INDEX_OU, keyValue, {
+        ascending,
+        limit,
+        startKey,
+    });
 }
 /**
  * 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;
-}
+const queryByAlias = vocabulary.serviceHandler({
+    alias: "queryByAlias",
+    description: "Query a single entity by human-friendly alias",
+    input: {
+        alias: { type: String, description: "Human-friendly alias" },
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+    },
+    service: async ({ alias, archived, deleted, model, ou, }) => {
+        const aliasStr = alias;
+        const archivedBool = archived;
+        const deletedBool = deleted;
+        const modelStr = model;
+        const ouStr = ou;
+        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
+        const keyValue = buildIndexAlias(ouStr, modelStr, aliasStr) + suffix;
+        const 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
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-async function queryByClass(params) {
-    const { archived, deleted, model, ou, recordClass, ...options } = params;
+async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, ou, recordClass, startKey, }) {
     const suffix = calculateSuffix({ archived, deleted });
     const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
-    return executeQuery(INDEX_CLASS, keyValue, options);
+    return executeQuery(INDEX_CLASS, keyValue, {
+        ascending,
+        limit,
+        startKey,
+    });
 }
 /**
  * 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
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-async function queryByType(params) {
-    const { archived, deleted, model, ou, type, ...options } = params;
+async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, type, }) {
     const suffix = calculateSuffix({ archived, deleted });
     const keyValue = buildIndexType(ou, model, type) + suffix;
-    return executeQuery(INDEX_TYPE, keyValue, options);
+    return executeQuery(INDEX_TYPE, keyValue, {
+        ascending,
+        limit,
+        startKey,
+    });
 }
 /**
  * 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;
-}
+const queryByXid = vocabulary.serviceHandler({
+    alias: "queryByXid",
+    description: "Query a single entity by external ID",
+    input: {
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+        xid: { type: String, description: "External ID" },
+    },
+    service: async ({ archived, deleted, model, ou, xid, }) => {
+        const archivedBool = archived;
+        const deletedBool = deleted;
+        const modelStr = model;
+        const ouStr = ou;
+        const xidStr = xid;
+        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
+        const keyValue = buildIndexXid(ouStr, modelStr, xidStr) + suffix;
+        const result = await executeQuery(INDEX_XID, keyValue, {
+            limit: 1,
+        });
+        return result.items[0] ?? null;
+    },
+});
 
 exports.APEX = APEX;
 exports.ARCHIVED_SUFFIX = ARCHIVED_SUFFIX;