@jaypie/dynamodb 0.0.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Finlayson Studio, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# Jaypie DynamoDB
+
+DynamoDB single-table storage utilities for Jaypie applications.
+
+See [Jaypie](https://github.com/finlaysonstudio/jaypie) for usage.
+
+## Changelog
+
+| Date       | Version | Summary        |
+| ---------- | ------- | -------------- |
+|  1/07/2026 |   0.1.0 | Initial commit |
+
+## License
+
+[MIT License](./LICENSE.txt). Published by Finlayson Studio

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

@@ -0,0 +1,483 @@
+'use strict';
+
+var clientDynamodb = require('@aws-sdk/client-dynamodb');
+var libDynamodb = require('@aws-sdk/lib-dynamodb');
+var errors = require('@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 clientDynamodb.DynamoDBClient({
+        ...(credentials && { credentials }),
+        ...(endpoint && { endpoint }),
+        region,
+    });
+    docClient = libDynamodb.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 errors.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 errors.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 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
+ */
+async function putEntity(params) {
+    const { entity } = params;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Auto-populate index keys
+    const indexedEntity = indexEntity(entity);
+    const command = new libDynamodb.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 libDynamodb.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 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;
+}
+/**
+ * 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;
+}
+
+/**
+ * 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 libDynamodb.QueryCommand({
+        ExclusiveStartKey: startKey,
+        ExpressionAttributeNames: {
+            "#pk": indexName,
+        },
+        ExpressionAttributeValues: {
+            ":pkValue": keyValue,
+        },
+        IndexName: indexName,
+        KeyConditionExpression: "#pk = :pkValue",
+        ...(limit && { Limit: limit }),
+        ScanIndexForward: ascending,
+        TableName: tableName,
+    });
+    const response = await docClient.send(command);
+    return {
+        items: (response.Items ?? []),
+        lastEvaluatedKey: response.LastEvaluatedKey,
+    };
+}
+/**
+ * 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;
+}
+
+exports.APEX = APEX;
+exports.ARCHIVED_SUFFIX = ARCHIVED_SUFFIX;
+exports.DELETED_SUFFIX = DELETED_SUFFIX;
+exports.INDEX_ALIAS = INDEX_ALIAS;
+exports.INDEX_CLASS = INDEX_CLASS;
+exports.INDEX_OU = INDEX_OU;
+exports.INDEX_TYPE = INDEX_TYPE;
+exports.INDEX_XID = INDEX_XID;
+exports.SEPARATOR = SEPARATOR;
+exports.archiveEntity = archiveEntity;
+exports.buildIndexAlias = buildIndexAlias;
+exports.buildIndexClass = buildIndexClass;
+exports.buildIndexOu = buildIndexOu;
+exports.buildIndexType = buildIndexType;
+exports.buildIndexXid = buildIndexXid;
+exports.calculateOu = calculateOu;
+exports.deleteEntity = deleteEntity;
+exports.destroyEntity = destroyEntity;
+exports.getDocClient = getDocClient;
+exports.getEntity = getEntity;
+exports.getTableName = getTableName;
+exports.indexEntity = indexEntity;
+exports.initClient = initClient;
+exports.isInitialized = isInitialized;
+exports.putEntity = putEntity;
+exports.queryByAlias = queryByAlias;
+exports.queryByClass = queryByClass;
+exports.queryByOu = queryByOu;
+exports.queryByType = queryByType;
+exports.queryByXid = queryByXid;
+exports.resetClient = resetClient;
+exports.updateEntity = updateEntity;
+//# sourceMappingURL=index.cjs.map