@openhi/constructs 0.0.111 → 0.0.113

package/lib/chunk-QJDHVMKT.mjs

@@ -0,0 +1,117 @@
+import {
+  ConflictError,
+  DomainError,
+  ValidationError
+} from "./chunk-FYHBHHWK.mjs";
+
+// src/data/operations/control/multi-write-operation.ts
+var TRANSACT_WRITE_ITEM_LIMIT = 100;
+async function executeMultiWrite(params) {
+  const { service, triples, token } = params;
+  if (triples.length === 0) {
+    throw new ValidationError(
+      "executeMultiWrite called with zero triples; at least one triple is required"
+    );
+  }
+  if (triples.length > TRANSACT_WRITE_ITEM_LIMIT) {
+    throw new ValidationError(
+      `executeMultiWrite received ${triples.length} triples; DynamoDB TransactWriteItems is limited to ${TRANSACT_WRITE_ITEM_LIMIT} items per call`,
+      {
+        details: {
+          itemsRequested: triples.length,
+          limit: TRANSACT_WRITE_ITEM_LIMIT
+        }
+      }
+    );
+  }
+  for (const [index, triple] of triples.entries()) {
+    if (!triple || typeof triple !== "object") {
+      throw new ValidationError(
+        `executeMultiWrite triple at index ${index} is not an object`
+      );
+    }
+    if (typeof triple.entity !== "string" || triple.entity.length === 0) {
+      throw new ValidationError(
+        `executeMultiWrite triple at index ${index} is missing a non-empty 'entity' key`
+      );
+    }
+    if (!isSupportedAction(triple.action)) {
+      throw new ValidationError(
+        `executeMultiWrite triple at index ${index} has unsupported action '${String(
+          triple.action
+        )}'; supported: 'put' | 'create' | 'delete'`
+      );
+    }
+    if (!triple.item || typeof triple.item !== "object") {
+      throw new ValidationError(
+        `executeMultiWrite triple at index ${index} is missing an 'item' payload`
+      );
+    }
+  }
+  let result;
+  try {
+    result = await service.transaction.write(
+      (entities) => triples.map((triple, index) => {
+        const transactEntity = entities[triple.entity];
+        if (transactEntity === void 0) {
+          throw new ValidationError(
+            `executeMultiWrite triple at index ${index} references unknown entity '${triple.entity}'; ensure the service exposes it`
+          );
+        }
+        switch (triple.action) {
+          case "put":
+            return transactEntity.put(triple.item).commit();
+          case "create":
+            return transactEntity.create(triple.item).commit();
+          case "delete":
+            return transactEntity.delete(triple.item).commit();
+          default:
+            throw new ValidationError(
+              `executeMultiWrite triple at index ${index} has unsupported action '${String(
+                triple.action
+              )}'`
+            );
+        }
+      })
+    ).go(token === void 0 ? void 0 : { token });
+  } catch (err) {
+    if (err instanceof DomainError) {
+      throw err;
+    }
+    throw new ConflictError(buildCancellationMessage(err), {
+      cause: err,
+      details: extractCancellationReasons(err)
+    });
+  }
+  if (result.canceled) {
+    throw new ConflictError(
+      "TransactWriteItems was canceled by DynamoDB (check CancellationReasons on the cause for details)",
+      { details: { canceled: true, data: result.data } }
+    );
+  }
+  return { itemsWritten: triples.length, canceled: false };
+}
+function isSupportedAction(value) {
+  return value === "put" || value === "create" || value === "delete";
+}
+function buildCancellationMessage(err) {
+  if (err instanceof Error && err.message) {
+    return `TransactWriteItems failed: ${err.message}`;
+  }
+  return "TransactWriteItems failed (no error message available)";
+}
+function extractCancellationReasons(err) {
+  if (err && typeof err === "object") {
+    const cancellationReasons = err.CancellationReasons;
+    if (cancellationReasons !== void 0) {
+      return { CancellationReasons: cancellationReasons };
+    }
+  }
+  return void 0;
+}
+
+export {
+  TRANSACT_WRITE_ITEM_LIMIT,
+  executeMultiWrite
+};
+//# sourceMappingURL=chunk-QJDHVMKT.mjs.map

package/lib/chunk-QJDHVMKT.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/data/operations/control/multi-write-operation.ts"],"sourcesContent":["/**\n * Operations-layer multi-write helper for the control plane.\n *\n * Per ADR-018 § Implementation Notes and the ADR-018 implementation\n * guide § 3, every cross-entity mutation in the control plane (canonical\n * record + adjacency-list projections) MUST flow through this helper.\n * Lambda handlers call operations; operations call this helper; nothing\n * under `data/operations/control/` may call `service.transaction.write`\n * directly after #1010 lands.\n *\n * The helper accepts an array of `{ entity, action, item }` triples,\n * maps each one to ElectroDB's transaction-write builder, and submits\n * the batch via `TransactWriteItems` — all-or-nothing atomicity. It\n * enforces the 100-item DynamoDB transaction ceiling at the helper\n * boundary and surfaces conditional-check / transaction-conflict\n * failures as typed domain errors so REST adapters can map to the\n * right HTTP status (409 / 400 / 500).\n *\n * Idempotency belongs to the caller — every call attempts a fresh\n * `TransactWriteItems`. Callers compose conditional expressions\n * (e.g. `vid` matches, `attribute_not_exists(PK)`) per triple via\n * ElectroDB's `where` builder; the helper does not invent conditions.\n *\n * Per ADR-018 Open Item Follow-up #2 the implementation uses ElectroDB's\n * `service.transaction.write` rather than a hand-rolled\n * `TransactWriteItemsCommand`. Reasons: (a) ElectroDB derives the\n * `TransactWriteItem` payload (Item attributes, GSI keys, watch-driven\n * fields) from the entity schema — hand-rolling would duplicate the\n * watch/derive logic and silently drift on schema changes; (b) it\n * preserves the existing single-write call-site idiom\n * (`service.entities.<x>.put({...}).go()` reads almost identically to\n * `entities.<x>.put({...}).commit()` inside the txn builder), keeping\n * the operations layer ergonomic; (c) ElectroDB's `canceled` flag and\n * `ElectroValidationError` propagation give us a single typed handle on\n * cancellation-vs-validation. We can drop to raw `TransactWriteItems`\n * later if a future operation needs DDB features ElectroDB has not yet\n * surfaced.\n *\n * @see ADR-018 § Implementation Notes\n * @see .state/adr-018-implementation-guide.md § 3 — Multi-Write Helper API Contract\n * @see .claude/rules/data-layer-layout.md\n */\n\nimport type { Entity, Service } from \"electrodb\";\nimport { ConflictError, DomainError, ValidationError } from \"../../errors\";\n\n/**\n * Maximum items allowed in a single DynamoDB `TransactWriteItems`\n * call (AWS, raised from 25 → 100 on 2024-09-23). The helper enforces\n * this ceiling at the boundary so callers do not silently lose the\n * tail of an oversized batch when DDB rejects the call.\n */\nexport const TRANSACT_WRITE_ITEM_LIMIT = 100 as const;\n\n/** Supported actions on a multi-write triple. */\nexport type MultiWriteAction = \"put\" | \"create\" | \"delete\";\n\n/**\n * A single entry in a multi-write call: which entity to act on, the\n * action, and the per-action payload.\n *\n * - `put` / `create` — `item` is the full record (matches\n *   `entity.put(item)` / `entity.create(item)` shape).\n * - `delete` — `item` is the key composite (matches\n *   `entity.delete(key)` shape).\n *\n * `entity` is a string key into the service's `entities` map (e.g.\n * `\"membership\"`, `\"tenant\"`). Using a string key avoids leaking the\n * transaction-bound entity reference across the helper boundary —\n * ElectroDB's `service.transaction.write(fn)` only honours entity\n * references that the closure-provided `entities` argument exposes.\n */\nexport interface MultiWriteTriple<EntityKey extends string = string> {\n  readonly entity: EntityKey;\n  readonly action: MultiWriteAction;\n  readonly item: Record<string, unknown>;\n}\n\n/** A service object exposing the ElectroDB `transaction.write` builder. */\ntype ServiceLike = Pick<\n  Service<Record<string, Entity<any, any, any, any>>>,\n  \"transaction\"\n>;\n\n/** Parameters for {@link executeMultiWrite}. */\nexport interface ExecuteMultiWriteParams<EntityKey extends string = string> {\n  /**\n   * ElectroDB `Service` (control-plane or data-plane) exposing\n   * `transaction.write` and the entity set the triples reference.\n   * Inject via `getDynamoControlService(tableName)` /\n   * `getDynamoDataService(tableName)` — matches the service-factory\n   * pattern every other operation under `data/operations/` uses.\n   */\n  readonly service: ServiceLike;\n  /**\n   * The triples to commit atomically. Order is preserved on the wire\n   * (ElectroDB submits them in the same order); duplicates are not\n   * de-duplicated by the helper.\n   */\n  readonly triples: ReadonlyArray<MultiWriteTriple<EntityKey>>;\n  /** Optional idempotency token forwarded to ElectroDB. */\n  readonly token?: string;\n}\n\n/** Successful multi-write result. */\nexport interface ExecuteMultiWriteResult {\n  /** Number of triples committed. */\n  readonly itemsWritten: number;\n  /**\n   * `canceled` flag returned by ElectroDB. Always `false` on the\n   * success path — failures throw {@link ConflictError} or\n   * {@link ValidationError}. Surfaced for completeness so callers can\n   * assert on it in tests if they wish.\n   */\n  readonly canceled: false;\n}\n\n/**\n * Submits `triples` as a single `TransactWriteItems` via ElectroDB's\n * `service.transaction.write` builder. All-or-nothing: every triple\n * lands or none does.\n *\n * Throws:\n * - {@link ValidationError} when `triples` is empty, exceeds the\n *   {@link TRANSACT_WRITE_ITEM_LIMIT}, references an entity that the\n *   service does not expose, or carries an unsupported `action`.\n * - {@link ConflictError} when DynamoDB cancels the transaction\n *   (e.g. `ConditionalCheckFailed`, `TransactionConflict`,\n *   `ProvisionedThroughputExceeded`). The original ElectroDB error\n *   (carrying `CancellationReasons`) is attached as `cause`.\n * - The original {@link DomainError} on rethrow if the caller's own\n *   validation hook surfaces one (e.g. nested ValidationError).\n *\n * Note on `update` / `patch` actions: not yet supported by the triple\n * shape because ElectroDB's transaction-write builder structures them\n * as `entity.update(key).set({...}).commit()` (key + delta), which\n * does not flatten cleanly into a single `item` payload. Add a\n * separate triple variant when the first consumer needs it; today\n * every ADR-018 multi-write is a `put` (canonical + projections) or a\n * `delete` (cascade rewriter). See ADR-018 § Open Item Follow-up #2.\n */\nexport async function executeMultiWrite<EntityKey extends string = string>(\n  params: ExecuteMultiWriteParams<EntityKey>,\n): Promise<ExecuteMultiWriteResult> {\n  const { service, triples, token } = params;\n\n  if (triples.length === 0) {\n    throw new ValidationError(\n      \"executeMultiWrite called with zero triples; at least one triple is required\",\n    );\n  }\n  if (triples.length > TRANSACT_WRITE_ITEM_LIMIT) {\n    throw new ValidationError(\n      `executeMultiWrite received ${triples.length} triples; DynamoDB TransactWriteItems is limited to ${TRANSACT_WRITE_ITEM_LIMIT} items per call`,\n      {\n        details: {\n          itemsRequested: triples.length,\n          limit: TRANSACT_WRITE_ITEM_LIMIT,\n        },\n      },\n    );\n  }\n\n  for (const [index, triple] of triples.entries()) {\n    if (!triple || typeof triple !== \"object\") {\n      throw new ValidationError(\n        `executeMultiWrite triple at index ${index} is not an object`,\n      );\n    }\n    if (typeof triple.entity !== \"string\" || triple.entity.length === 0) {\n      throw new ValidationError(\n        `executeMultiWrite triple at index ${index} is missing a non-empty 'entity' key`,\n      );\n    }\n    if (!isSupportedAction(triple.action)) {\n      throw new ValidationError(\n        `executeMultiWrite triple at index ${index} has unsupported action '${String(\n          triple.action,\n        )}'; supported: 'put' | 'create' | 'delete'`,\n      );\n    }\n    if (!triple.item || typeof triple.item !== \"object\") {\n      throw new ValidationError(\n        `executeMultiWrite triple at index ${index} is missing an 'item' payload`,\n      );\n    }\n  }\n\n  let result: { canceled: boolean; data: unknown };\n  try {\n    result = await service.transaction\n      .write((entities: Record<string, any>) =>\n        triples.map((triple, index) => {\n          const transactEntity = entities[triple.entity];\n          if (transactEntity === undefined) {\n            throw new ValidationError(\n              `executeMultiWrite triple at index ${index} references unknown entity '${triple.entity}'; ensure the service exposes it`,\n            );\n          }\n          switch (triple.action) {\n            case \"put\":\n              return transactEntity.put(triple.item).commit();\n            case \"create\":\n              return transactEntity.create(triple.item).commit();\n            case \"delete\":\n              return transactEntity.delete(triple.item).commit();\n            default:\n              // Exhaustiveness guard; pre-flight validates this already.\n              throw new ValidationError(\n                `executeMultiWrite triple at index ${index} has unsupported action '${String(\n                  (triple as MultiWriteTriple).action,\n                )}'`,\n              );\n          }\n        }),\n      )\n      .go(token === undefined ? undefined : { token });\n  } catch (err) {\n    // Pre-flight ValidationErrors thrown inside the builder bubble\n    // through unchanged so callers see a 400, not a 409.\n    if (err instanceof DomainError) {\n      throw err;\n    }\n    throw new ConflictError(buildCancellationMessage(err), {\n      cause: err,\n      details: extractCancellationReasons(err),\n    });\n  }\n\n  if (result.canceled) {\n    throw new ConflictError(\n      \"TransactWriteItems was canceled by DynamoDB (check CancellationReasons on the cause for details)\",\n      { details: { canceled: true, data: result.data } },\n    );\n  }\n\n  return { itemsWritten: triples.length, canceled: false };\n}\n\nfunction isSupportedAction(value: unknown): value is MultiWriteAction {\n  return value === \"put\" || value === \"create\" || value === \"delete\";\n}\n\nfunction buildCancellationMessage(err: unknown): string {\n  if (err instanceof Error && err.message) {\n    return `TransactWriteItems failed: ${err.message}`;\n  }\n  return \"TransactWriteItems failed (no error message available)\";\n}\n\nfunction extractCancellationReasons(err: unknown): unknown {\n  if (err && typeof err === \"object\") {\n    const cancellationReasons = (err as { CancellationReasons?: unknown })\n      .CancellationReasons;\n    if (cancellationReasons !== undefined) {\n      return { CancellationReasons: cancellationReasons };\n    }\n  }\n  return undefined;\n}\n"],"mappings":"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","names":[]}

package/lib/{chunk-IS4VQRI4.mjs → chunk-QMBJ4VHC.mjs}

@@ -1,47 +1,14 @@
+import {
+  NotFoundError
+} from "./chunk-FYHBHHWK.mjs";
 import {
   SHARD_COUNT,
-  computeShard,
+  computeShard
+} from "./chunk-6NBGYGFL.mjs";
+import {
   defaultTableName,
   dynamoClient
-} from "./chunk-QR5JVSCF.mjs";
-
-// src/data/errors/domain-errors.ts
-var DomainError = class extends Error {
-  constructor(message, code, options) {
-    super(message, options);
-    this.name = this.constructor.name;
-    this.code = code;
-    this.details = options?.details;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var NotFoundError = class extends DomainError {
-  constructor(message, options) {
-    super(message, "NOT_FOUND", options);
-  }
-};
-var ValidationError = class extends DomainError {
-  constructor(message, options) {
-    super(message, "VALIDATION", options);
-  }
-};
-var ConflictError = class extends DomainError {
-  constructor(message, options) {
-    super(message, "CONFLICT", options);
-  }
-};
-var ForbiddenError = class extends DomainError {
-  constructor(message, options) {
-    super(message, "FORBIDDEN", options);
-  }
-};
-function domainErrorToHttpStatus(err) {
-  if (err instanceof NotFoundError) return 404;
-  if (err instanceof ValidationError) return 400;
-  if (err instanceof ConflictError) return 409;
-  if (err instanceof ForbiddenError) return 403;
-  return null;
-}
+} from "./chunk-TRY7JGWO.mjs";
 
 // src/data/dynamo/dynamo-data-service.ts
 import { Service } from "electrodb";
@@ -1062,7 +1029,8 @@ var dataPlaneService = new Service(dataPlaneEntities, {
   client: dynamoClient
 });
 var DynamoDataService = {
-  entities: dataPlaneService.entities
+  entities: dataPlaneService.entities,
+  transaction: dataPlaneService.transaction
 };
 function getDynamoDataService(tableName) {
   const resolved = tableName ?? defaultTableName;
@@ -1071,7 +1039,8 @@ function getDynamoDataService(tableName) {
     client: dynamoClient
   });
   return {
-    entities: service.entities
+    entities: service.entities,
+    transaction: service.transaction
   };
 }
 
@@ -1369,10 +1338,6 @@ async function updateDataEntityById(entity, tenantId, workspaceId, id, resourceL
 }
 
 export {
-  NotFoundError,
-  ValidationError,
-  ForbiddenError,
-  domainErrorToHttpStatus,
   getDynamoDataService,
   compressResource,
   decompressResource,
@@ -1387,4 +1352,4 @@ export {
   buildUpdatedResourceWithAudit,
   updateDataEntityById
 };
-//# sourceMappingURL=chunk-IS4VQRI4.mjs.map
+//# sourceMappingURL=chunk-QMBJ4VHC.mjs.map