@celerity-sdk/datastore 0.3.1 → 0.4.0

package/dist/index.js

@@ -1 +1,632 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/types.ts
+var DatastoreClient = /* @__PURE__ */ Symbol.for("DatastoreClient");
+
+// src/providers/dynamodb/dynamodb-datastore-client.ts
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+
+// src/providers/dynamodb/dynamodb-datastore.ts
+import createDebug2 from "debug";
+import { GetCommand, PutCommand, DeleteCommand, BatchGetCommand, BatchWriteCommand } from "@aws-sdk/lib-dynamodb";
+
+// src/errors.ts
+var DatastoreError = class extends Error {
+  static {
+    __name(this, "DatastoreError");
+  }
+  table;
+  constructor(message, table, options) {
+    super(message, options), this.table = table;
+    this.name = "DatastoreError";
+  }
+};
+var ConditionalCheckFailedError = class extends DatastoreError {
+  static {
+    __name(this, "ConditionalCheckFailedError");
+  }
+  constructor(table, options) {
+    super(`Conditional check failed on table "${table}"`, table, options);
+    this.name = "ConditionalCheckFailedError";
+  }
+};
+
+// src/providers/dynamodb/dynamodb-item-listing.ts
+import createDebug from "debug";
+import { QueryCommand, ScanCommand } from "@aws-sdk/lib-dynamodb";
+
+// src/providers/dynamodb/expressions.ts
+var COMPARISON_OPERATORS = {
+  eq: "=",
+  ne: "<>",
+  lt: "<",
+  le: "<=",
+  gt: ">",
+  ge: ">="
+};
+function buildKeyConditionExpression(key, range) {
+  const names = {};
+  const values = {};
+  let counter = 0;
+  const pkName = `#k${counter}`;
+  const pkValue = `:k${counter}`;
+  names[pkName] = key.name;
+  values[pkValue] = key.value;
+  counter++;
+  let expression = `${pkName} = ${pkValue}`;
+  if (range) {
+    const skName = `#k${counter}`;
+    names[skName] = range.name;
+    switch (range.operator) {
+      case "eq":
+      case "lt":
+      case "le":
+      case "gt":
+      case "ge": {
+        const skValue = `:k${counter}`;
+        values[skValue] = range.value;
+        expression += ` AND ${skName} ${COMPARISON_OPERATORS[range.operator]} ${skValue}`;
+        break;
+      }
+      case "between": {
+        const lowVal = `:k${counter}a`;
+        const highVal = `:k${counter}b`;
+        values[lowVal] = range.low;
+        values[highVal] = range.high;
+        expression += ` AND ${skName} BETWEEN ${lowVal} AND ${highVal}`;
+        break;
+      }
+      case "startsWith": {
+        const skValue = `:k${counter}`;
+        values[skValue] = range.value;
+        expression += ` AND begins_with(${skName}, ${skValue})`;
+        break;
+      }
+    }
+  }
+  return {
+    expression,
+    names,
+    values
+  };
+}
+__name(buildKeyConditionExpression, "buildKeyConditionExpression");
+function buildFilterExpression(conditions) {
+  const condArray = Array.isArray(conditions) ? conditions : [
+    conditions
+  ];
+  const names = {};
+  const values = {};
+  const parts = [];
+  let counter = 0;
+  for (const cond of condArray) {
+    const attrName = `#f${counter}`;
+    names[attrName] = cond.name;
+    switch (cond.operator) {
+      case "eq":
+      case "ne":
+      case "lt":
+      case "le":
+      case "gt":
+      case "ge": {
+        const valKey = `:f${counter}`;
+        values[valKey] = cond.value;
+        parts.push(`${attrName} ${COMPARISON_OPERATORS[cond.operator]} ${valKey}`);
+        break;
+      }
+      case "between": {
+        const lowVal = `:f${counter}a`;
+        const highVal = `:f${counter}b`;
+        values[lowVal] = cond.low;
+        values[highVal] = cond.high;
+        parts.push(`${attrName} BETWEEN ${lowVal} AND ${highVal}`);
+        break;
+      }
+      case "startsWith":
+      case "contains": {
+        const valKey = `:f${counter}`;
+        values[valKey] = cond.value;
+        const fnName = cond.operator === "startsWith" ? "begins_with" : "contains";
+        parts.push(`${fnName}(${attrName}, ${valKey})`);
+        break;
+      }
+      case "exists":
+        parts.push(`attribute_exists(${attrName})`);
+        break;
+    }
+    counter++;
+  }
+  return {
+    expression: parts.join(" AND "),
+    names,
+    values
+  };
+}
+__name(buildFilterExpression, "buildFilterExpression");
+
+// src/providers/dynamodb/dynamodb-item-listing.ts
+var debug = createDebug("celerity:datastore:dynamodb");
+function encodeCursor(lastEvaluatedKey) {
+  const state = {
+    lastEvaluatedKey
+  };
+  return Buffer.from(JSON.stringify(state)).toString("base64url");
+}
+__name(encodeCursor, "encodeCursor");
+function decodeCursor(cursor) {
+  return JSON.parse(Buffer.from(cursor, "base64url").toString("utf-8"));
+}
+__name(decodeCursor, "decodeCursor");
+var DynamoDBItemListing = class {
+  static {
+    __name(this, "DynamoDBItemListing");
+  }
+  client;
+  tableName;
+  mode;
+  options;
+  tracer;
+  _cursor;
+  constructor(client, tableName, mode, options, tracer) {
+    this.client = client;
+    this.tableName = tableName;
+    this.mode = mode;
+    this.options = options;
+    this.tracer = tracer;
+    this._cursor = options.cursor;
+  }
+  get cursor() {
+    return this._cursor;
+  }
+  async *[Symbol.asyncIterator]() {
+    const cursorState = this._cursor ? decodeCursor(this._cursor) : void 0;
+    let exclusiveStartKey = cursorState?.lastEvaluatedKey;
+    do {
+      debug("%s page %s key=%o", this.mode, this.tableName, exclusiveStartKey ?? "(start)");
+      const response = await this.fetchPage(exclusiveStartKey);
+      for (const item of response.Items ?? []) {
+        yield item;
+      }
+      exclusiveStartKey = response.LastEvaluatedKey;
+      if (exclusiveStartKey) {
+        this._cursor = encodeCursor(exclusiveStartKey);
+      } else {
+        this._cursor = void 0;
+      }
+    } while (exclusiveStartKey);
+  }
+  async fetchPage(exclusiveStartKey) {
+    const command = this.mode === "query" ? this.buildQueryCommand(exclusiveStartKey) : this.buildScanCommand(exclusiveStartKey);
+    const doFetch = /* @__PURE__ */ __name(async () => {
+      try {
+        return await this.client.send(command);
+      } catch (error) {
+        throw new DatastoreError(`Failed to ${this.mode} table "${this.tableName}"`, this.tableName, {
+          cause: error
+        });
+      }
+    }, "doFetch");
+    if (!this.tracer) return doFetch();
+    return this.tracer.withSpan(`celerity.datastore.${this.mode}_page`, () => doFetch(), {
+      "datastore.table": this.tableName
+    });
+  }
+  buildQueryCommand(exclusiveStartKey) {
+    const opts = this.options;
+    const keyExpr = buildKeyConditionExpression(opts.key, opts.range);
+    const filterExpr = opts.filter ? buildFilterExpression(opts.filter) : void 0;
+    return new QueryCommand({
+      TableName: this.tableName,
+      IndexName: opts.indexName,
+      KeyConditionExpression: keyExpr.expression,
+      FilterExpression: filterExpr?.expression,
+      ExpressionAttributeNames: {
+        ...keyExpr.names,
+        ...filterExpr?.names
+      },
+      ExpressionAttributeValues: {
+        ...keyExpr.values,
+        ...filterExpr?.values
+      },
+      ScanIndexForward: opts.sortAscending,
+      Limit: opts.maxResults,
+      ExclusiveStartKey: exclusiveStartKey,
+      ConsistentRead: opts.consistentRead
+    });
+  }
+  buildScanCommand(exclusiveStartKey) {
+    const opts = this.options;
+    const filterExpr = opts.filter ? buildFilterExpression(opts.filter) : void 0;
+    return new ScanCommand({
+      TableName: this.tableName,
+      IndexName: opts.indexName,
+      FilterExpression: filterExpr?.expression,
+      ExpressionAttributeNames: filterExpr?.names && Object.keys(filterExpr.names).length > 0 ? filterExpr.names : void 0,
+      ExpressionAttributeValues: filterExpr?.values && Object.keys(filterExpr.values).length > 0 ? filterExpr.values : void 0,
+      Limit: opts.maxResults,
+      ExclusiveStartKey: exclusiveStartKey,
+      ConsistentRead: opts.consistentRead
+    });
+  }
+};
+
+// src/providers/dynamodb/errors.ts
+function isConditionalCheckFailedError(error) {
+  if (!(error instanceof Error)) return false;
+  return error.name === "ConditionalCheckFailedException";
+}
+__name(isConditionalCheckFailedError, "isConditionalCheckFailedError");
+
+// src/providers/dynamodb/dynamodb-datastore.ts
+var debug2 = createDebug2("celerity:datastore:dynamodb");
+var DynamoDBDatastore = class {
+  static {
+    __name(this, "DynamoDBDatastore");
+  }
+  tableName;
+  client;
+  tracer;
+  constructor(tableName, client, tracer) {
+    this.tableName = tableName;
+    this.client = client;
+    this.tracer = tracer;
+  }
+  async getItem(key, options) {
+    debug2("getItem %s %o", this.tableName, key);
+    return this.traced("celerity.datastore.get_item", {
+      "datastore.table": this.tableName
+    }, async () => {
+      try {
+        const response = await this.client.send(new GetCommand({
+          TableName: this.tableName,
+          Key: key,
+          ConsistentRead: options?.consistentRead
+        }));
+        return response.Item ?? null;
+      } catch (error) {
+        throw new DatastoreError(`Failed to get item from table "${this.tableName}"`, this.tableName, {
+          cause: error
+        });
+      }
+    });
+  }
+  async putItem(item, options) {
+    debug2("putItem %s", this.tableName);
+    return this.traced("celerity.datastore.put_item", {
+      "datastore.table": this.tableName
+    }, async () => {
+      try {
+        const conditionParams = options?.condition ? buildFilterExpression(options.condition) : void 0;
+        await this.client.send(new PutCommand({
+          TableName: this.tableName,
+          Item: item,
+          ConditionExpression: conditionParams?.expression,
+          ExpressionAttributeNames: conditionParams?.names,
+          ExpressionAttributeValues: conditionParams?.values
+        }));
+      } catch (error) {
+        if (isConditionalCheckFailedError(error)) {
+          throw new ConditionalCheckFailedError(this.tableName, {
+            cause: error
+          });
+        }
+        throw new DatastoreError(`Failed to put item in table "${this.tableName}"`, this.tableName, {
+          cause: error
+        });
+      }
+    });
+  }
+  async deleteItem(key, options) {
+    debug2("deleteItem %s %o", this.tableName, key);
+    return this.traced("celerity.datastore.delete_item", {
+      "datastore.table": this.tableName
+    }, async () => {
+      try {
+        const conditionParams = options?.condition ? buildFilterExpression(options.condition) : void 0;
+        await this.client.send(new DeleteCommand({
+          TableName: this.tableName,
+          Key: key,
+          ConditionExpression: conditionParams?.expression,
+          ExpressionAttributeNames: conditionParams?.names,
+          ExpressionAttributeValues: conditionParams?.values
+        }));
+      } catch (error) {
+        if (isConditionalCheckFailedError(error)) {
+          throw new ConditionalCheckFailedError(this.tableName, {
+            cause: error
+          });
+        }
+        throw new DatastoreError(`Failed to delete item from table "${this.tableName}"`, this.tableName, {
+          cause: error
+        });
+      }
+    });
+  }
+  query(options) {
+    debug2("query %s pk=%s", this.tableName, options.key.name);
+    return new DynamoDBItemListing(this.client, this.tableName, "query", options, this.tracer);
+  }
+  scan(options) {
+    debug2("scan %s", this.tableName);
+    return new DynamoDBItemListing(this.client, this.tableName, "scan", options ?? {}, this.tracer);
+  }
+  async batchGetItems(keys, options) {
+    debug2("batchGetItems %s count=%d", this.tableName, keys.length);
+    return this.traced("celerity.datastore.batch_get_items", {
+      "datastore.table": this.tableName,
+      "datastore.batch_size": keys.length
+    }, async () => {
+      try {
+        const response = await this.client.send(new BatchGetCommand({
+          RequestItems: {
+            [this.tableName]: {
+              Keys: keys,
+              ConsistentRead: options?.consistentRead
+            }
+          }
+        }));
+        const items = response.Responses?.[this.tableName] ?? [];
+        const unprocessedKeys = response.UnprocessedKeys?.[this.tableName]?.Keys ?? [];
+        return {
+          items,
+          unprocessedKeys
+        };
+      } catch (error) {
+        throw new DatastoreError(`Failed to batch get items from table "${this.tableName}"`, this.tableName, {
+          cause: error
+        });
+      }
+    });
+  }
+  async batchWriteItems(operations) {
+    debug2("batchWriteItems %s count=%d", this.tableName, operations.length);
+    return this.traced("celerity.datastore.batch_write_items", {
+      "datastore.table": this.tableName,
+      "datastore.batch_size": operations.length
+    }, async () => {
+      try {
+        const writeRequests = operations.map((op) => {
+          if (op.type === "put") {
+            return {
+              PutRequest: {
+                Item: op.item
+              }
+            };
+          }
+          return {
+            DeleteRequest: {
+              Key: op.key
+            }
+          };
+        });
+        const response = await this.client.send(new BatchWriteCommand({
+          RequestItems: {
+            [this.tableName]: writeRequests
+          }
+        }));
+        const unprocessedRequests = response.UnprocessedItems?.[this.tableName] ?? [];
+        const unprocessedOperations = unprocessedRequests.map((req) => {
+          if (req.PutRequest) {
+            return {
+              type: "put",
+              item: req.PutRequest.Item
+            };
+          }
+          return {
+            type: "delete",
+            key: req.DeleteRequest.Key
+          };
+        });
+        return {
+          unprocessedOperations
+        };
+      } catch (error) {
+        throw new DatastoreError(`Failed to batch write items to table "${this.tableName}"`, this.tableName, {
+          cause: error
+        });
+      }
+    });
+  }
+  traced(name, attributes, fn) {
+    if (!this.tracer) return fn();
+    return this.tracer.withSpan(name, (span) => fn(span), attributes);
+  }
+};
+
+// src/providers/dynamodb/config.ts
+function captureDynamoDBConfig() {
+  return {
+    region: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION,
+    endpoint: process.env.AWS_ENDPOINT_URL,
+    credentials: process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY ? {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+    } : void 0
+  };
+}
+__name(captureDynamoDBConfig, "captureDynamoDBConfig");
+
+// src/providers/dynamodb/dynamodb-datastore-client.ts
+var DynamoDBDatastoreClient = class {
+  static {
+    __name(this, "DynamoDBDatastoreClient");
+  }
+  tracer;
+  client = null;
+  docClient = null;
+  config;
+  constructor(config, tracer) {
+    this.tracer = tracer;
+    this.config = config ?? captureDynamoDBConfig();
+  }
+  datastore(name) {
+    return new DynamoDBDatastore(name, this.getDocClient(), this.tracer);
+  }
+  close() {
+    this.docClient?.destroy();
+    this.client?.destroy();
+    this.docClient = null;
+    this.client = null;
+  }
+  getDocClient() {
+    if (!this.docClient) {
+      this.client = new DynamoDBClient({
+        region: this.config.region,
+        endpoint: this.config.endpoint,
+        credentials: this.config.credentials
+      });
+      this.docClient = DynamoDBDocumentClient.from(this.client, {
+        marshallOptions: {
+          removeUndefinedValues: true
+        }
+      });
+    }
+    return this.docClient;
+  }
+};
+
+// src/factory.ts
+import { resolveConfig } from "@celerity-sdk/config";
+function createDatastoreClient(options) {
+  const resolved = resolveConfig("datastore");
+  const provider = options?.provider ?? resolved.provider;
+  switch (provider) {
+    case "aws":
+      return new DynamoDBDatastoreClient(options?.aws, options?.tracer);
+    case "local":
+      return createLocalClient(options);
+    default:
+      throw new Error(`Unsupported datastore provider: "${provider}"`);
+  }
+}
+__name(createDatastoreClient, "createDatastoreClient");
+function createLocalClient(options) {
+  const deployTarget = options?.deployTarget?.toLowerCase();
+  switch (deployTarget) {
+    case "aws":
+    case "aws-serverless":
+    case void 0: {
+      const localConfig = {
+        ...captureDynamoDBConfig(),
+        ...options?.aws
+      };
+      return new DynamoDBDatastoreClient(localConfig, options?.tracer);
+    }
+    // case "gcloud":
+    // case "gcloud-serverless":
+    //   v1: Firestore emulator
+    // case "azure":
+    // case "azure-serverless":
+    //   v1: Cosmos DB emulator
+    default:
+      throw new Error(`Unsupported local datastore deploy target: "${deployTarget}". Only AWS is supported in v0.`);
+  }
+}
+__name(createLocalClient, "createLocalClient");
+
+// src/decorators.ts
+import "reflect-metadata";
+import { INJECT_METADATA, USE_RESOURCE_METADATA } from "@celerity-sdk/common";
+function datastoreToken(resourceName) {
+  return /* @__PURE__ */ Symbol.for(`celerity:datastore:${resourceName}`);
+}
+__name(datastoreToken, "datastoreToken");
+var DEFAULT_DATASTORE_TOKEN = /* @__PURE__ */ Symbol.for("celerity:datastore:default");
+function Datastore(resourceName) {
+  return (target, _propertyKey, parameterIndex) => {
+    const token = resourceName ? datastoreToken(resourceName) : DEFAULT_DATASTORE_TOKEN;
+    const existing = Reflect.getOwnMetadata(INJECT_METADATA, target) ?? /* @__PURE__ */ new Map();
+    existing.set(parameterIndex, token);
+    Reflect.defineMetadata(INJECT_METADATA, existing, target);
+    if (resourceName) {
+      const resources = Reflect.getOwnMetadata(USE_RESOURCE_METADATA, target) ?? [];
+      if (!resources.includes(resourceName)) {
+        Reflect.defineMetadata(USE_RESOURCE_METADATA, [
+          ...resources,
+          resourceName
+        ], target);
+      }
+    }
+  };
+}
+__name(Datastore, "Datastore");
+
+// src/helpers.ts
+function getDatastore(container, resourceName) {
+  const token = resourceName ? datastoreToken(resourceName) : DEFAULT_DATASTORE_TOKEN;
+  return container.resolve(token);
+}
+__name(getDatastore, "getDatastore");
+
+// src/layer.ts
+import createDebug3 from "debug";
+import { TRACER_TOKEN, CONFIG_SERVICE_TOKEN } from "@celerity-sdk/common";
+import { captureResourceLinks, getLinksOfType, RESOURCE_CONFIG_NAMESPACE } from "@celerity-sdk/config";
+var debug3 = createDebug3("celerity:datastore");
+function captureDatastoreLayerConfig() {
+  return {
+    deployTarget: process.env.CELERITY_DEPLOY_TARGET
+  };
+}
+__name(captureDatastoreLayerConfig, "captureDatastoreLayerConfig");
+var DatastoreLayer = class {
+  static {
+    __name(this, "DatastoreLayer");
+  }
+  initialized = false;
+  config = null;
+  async handle(context, next) {
+    if (!this.initialized) {
+      this.config = captureDatastoreLayerConfig();
+      const tracer = context.container.has(TRACER_TOKEN) ? await context.container.resolve(TRACER_TOKEN) : void 0;
+      const client = createDatastoreClient({
+        tracer,
+        deployTarget: this.config.deployTarget
+      });
+      debug3("registering DatastoreClient");
+      context.container.register("DatastoreClient", {
+        useValue: client
+      });
+      const links = captureResourceLinks();
+      const datastoreLinks = getLinksOfType(links, "datastore");
+      if (datastoreLinks.size > 0) {
+        const configService = await context.container.resolve(CONFIG_SERVICE_TOKEN);
+        const resourceConfig = configService.namespace(RESOURCE_CONFIG_NAMESPACE);
+        for (const [resourceName, configKey] of datastoreLinks) {
+          const actualName = await resourceConfig.getOrThrow(configKey);
+          debug3("registered datastore resource %s \u2192 %s", resourceName, actualName);
+          context.container.register(datastoreToken(resourceName), {
+            useValue: client.datastore(actualName)
+          });
+        }
+        if (datastoreLinks.size === 1) {
+          const [, configKey] = [
+            ...datastoreLinks.entries()
+          ][0];
+          const actualName = await resourceConfig.getOrThrow(configKey);
+          debug3("registered default datastore \u2192 %s", actualName);
+          context.container.register(DEFAULT_DATASTORE_TOKEN, {
+            useValue: client.datastore(actualName)
+          });
+        }
+      }
+      this.initialized = true;
+    }
+    return next();
+  }
+};
+export {
+  ConditionalCheckFailedError,
+  DEFAULT_DATASTORE_TOKEN,
+  Datastore,
+  DatastoreClient,
+  DatastoreError,
+  DatastoreLayer,
+  DynamoDBDatastoreClient,
+  createDatastoreClient,
+  datastoreToken,
+  getDatastore
+};
 //# sourceMappingURL=index.js.map