@webda/aws 4.0.0-beta.2 → 4.0.0-beta.4

package/lib/services/dynamodb.service.d.ts

@@ -0,0 +1,298 @@
+import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
+import { MemoryRepository, Store, StoreParameters } from "@webda/core";
+import type { ModelClass, Repository } from "@webda/core";
+import * as WebdaQL from "@webda/ql";
+import { WorkerOutput } from "@webda/workout";
+import { AWSServiceParameters } from "./aws-parameters.js";
+import type { CloudFormationContributor, CloudFormationDeployerInfo } from "./contributors.js";
+/**
+ * DynamoDB global secondary indexes definition
+ */
+export interface DynamoGlobalIndexes {
+    [key: string]: {
+        /**
+         * Hash key of the index
+         */
+        key: string;
+        /**
+         * Range key of the index
+         */
+        sort?: string;
+    };
+}
+/**
+ * Define DynamoDB parameters
+ */
+export declare class DynamoStoreParameters extends StoreParameters implements AWSServiceParameters {
+    /**
+     * Custom endpoint (localstack, minio, ...)
+     */
+    endpoint?: string;
+    /**
+     * Static credentials, default to the AWS environment variables
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /**
+     * AWS region
+     * @default "us-east-1"
+     */
+    region?: string;
+    /**
+     * Table name
+     */
+    table: string;
+    /**
+     * Per-model table name overrides, keyed by model identifier
+     *
+     * Models not listed use `table`
+     */
+    tables?: {
+        [modelIdentifier: string]: string;
+    };
+    /**
+     * Additional global indexes
+     */
+    globalIndexes?: DynamoGlobalIndexes;
+    /**
+     * CloudFormation customization
+     */
+    CloudFormation?: any;
+    /**
+     * Skip CloudFormation on deploy
+     */
+    CloudFormationSkip?: boolean;
+    /**
+     * Number of items to retrieve per scan page
+     */
+    scanPage?: number;
+    /**
+     * @override
+     * @param params - raw parameters
+     * @returns this
+     */
+    load(params?: any): this;
+}
+/**
+ * Result of a DynamoDB find before applying the residual filter
+ */
+export interface DynamoFindResult<T> {
+    /**
+     * Items returned by DynamoDB
+     */
+    results: T[];
+    /**
+     * Part of the query that DynamoDB cannot evaluate
+     */
+    filter: WebdaQL.Expression;
+    /**
+     * Next page token
+     */
+    continuationToken?: string;
+}
+/**
+ * Clean an object to store in DynamoDB
+ *
+ * Dates are converted to ISO strings, empty strings and undefined values are removed
+ *
+ * @param object - the value to clean
+ * @returns the cleaned value
+ */
+export declare function cleanObject(object: any): any;
+/**
+ * DynamoDB-backed repository for a single model class
+ *
+ * Every object is stored as one item, keyed by the string primary key in the
+ * `uuid` hash key attribute.
+ */
+export declare class DynamoRepository<T extends ModelClass> extends MemoryRepository<T> {
+    protected readonly client: DynamoDBDocument;
+    protected readonly table: string;
+    protected readonly globalIndexes: DynamoGlobalIndexes;
+    protected readonly scanPage?: number;
+    protected readonly storeName: string;
+    /**
+     * Create a new DynamoRepository
+     * @param model - the model class
+     * @param pks - primary key field names
+     * @param client - the DynamoDB document client
+     * @param table - the table name
+     * @param globalIndexes - global secondary indexes usable by queries
+     * @param scanPage - scan page size used by __clean
+     * @param storeName - store name used in errors
+     * @param separator - primary key separator
+     */
+    constructor(model: T, pks: string[], client: DynamoDBDocument, table: string, globalIndexes?: DynamoGlobalIndexes, scanPage?: number, storeName?: string, separator?: string);
+    /**
+     * The backing table name
+     * @returns the table name
+     */
+    getTable(): string;
+    /**
+     * Return the DynamoDB key of an object or primary key
+     * @param primaryKey - the object or primary key
+     * @returns the string key
+     */
+    protected getKey(primaryKey: any): string;
+    /**
+     * Convert a model or plain object to a DynamoDB item
+     * @param data - the object to convert
+     * @returns the item
+     */
+    toItem(data: any): any;
+    /**
+     * Convert a DynamoDB item to a model instance
+     *
+     * The `__type` attribute is used to instantiate the right subclass
+     * @param item - the DynamoDB item
+     * @returns the model instance
+     */
+    fromItem(item: any): InstanceType<T>;
+    /**
+     * Add a write condition to the DynamoDB parameters
+     * @param params - the DynamoDB parameters
+     * @param writeCondition - the expected value
+     * @param field - the field to check
+     */
+    setWriteCondition(params: any, writeCondition: any, field: string): void;
+    /**
+     * Build a document path expression for an attribute like `team.id`
+     * @param attribute - the attribute path
+     * @param names - expression attribute names to fill
+     * @param prefix - placeholder prefix
+     * @returns the path expression
+     */
+    protected attributePath(attribute: string, names: any, prefix: string): string;
+    /** @override */
+    get(primaryKey: any): Promise<any>;
+    /** @override */
+    exists(primaryKey: any): Promise<boolean>;
+    /** @override */
+    create(data: any, save?: boolean): Promise<any>;
+    /** @override */
+    update(data: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    patch(primaryKey: any, data: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    delete(primaryKey: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    removeAttribute(primaryKey: any, attribute: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    incrementAttributes(primaryKey: any, info: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    upsertItemToCollection(primaryKey: any, collection: any, item: any, index?: number, itemWriteConditionField?: any, itemWriteCondition?: any): Promise<void>;
+    /** @override */
+    deleteItemFromCollection(primaryKey: any, collection: any, index: number, itemWriteConditionField?: any, itemWriteCondition?: any): Promise<void>;
+    /**
+     * Translate a WebdaQL query into a DynamoDB scan or query
+     *
+     * A query on the hash key or on a global index hash key with `=` uses a DynamoDB Query,
+     * anything else is a Scan. The part of the expression DynamoDB cannot evaluate is
+     * returned in `filter` and must be applied on the results.
+     *
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html
+     * @param query - the parsed query
+     * @returns the items and the residual filter
+     */
+    find(query: WebdaQL.Query): Promise<DynamoFindResult<InstanceType<T>>>;
+    /**
+     * Query the table
+     *
+     * Pages are retrieved until the limit is reached, applying the part of the
+     * filter that DynamoDB cannot evaluate and restricting to the model hierarchy
+     * @override
+     * @param query - the WebdaQL query
+     * @returns the results and the continuation token
+     */
+    query(query: string | any): Promise<{
+        results: InstanceType<T>[];
+        continuationToken?: string;
+    }>;
+    /**
+     * Iterate over the query results
+     * @override
+     * @param query - the WebdaQL query
+     */
+    iterate(query: string): AsyncGenerator<InstanceType<T>, any, any>;
+    /**
+     * Delete all items from the table (used in tests)
+     */
+    __clean(): Promise<void>;
+}
+/**
+ * DynamoStore handles the DynamoDB
+ *
+ * Parameters:
+ *   accessKeyId: '' // try WEBDA_AWS_KEY env variable if not found
+ *   secretAccessKey: '' // try WEBDA_AWS_SECRET env variable if not found
+ *   table: ''
+ *   region: ''
+ *
+ * The table must have a `uuid` string hash key
+ *
+ * @WebdaModda
+ */
+export declare class DynamoStore<K extends DynamoStoreParameters = DynamoStoreParameters> extends Store<K> implements CloudFormationContributor {
+    _client: DynamoDBDocument;
+    /**
+     * Create the AWS client
+     * @returns this
+     */
+    resolve(): this;
+    /**
+     * Copy one DynamoDB table to another
+     *
+     * @param output - worker output to report progress
+     * @param source - source table
+     * @param target - target table
+     */
+    static copyTable(output: WorkerOutput, source: string, target: string): Promise<void>;
+    /**
+     * Resolve the table name for a given model class
+     *
+     * `tables[identifier]` overrides the default `table`
+     * @param model - the model class
+     * @returns the table name
+     */
+    resolveTable(model: ModelClass): string;
+    /**
+     * Build the DynamoRepository for a model
+     *
+     * The result is cached per model class
+     * @param model - the model class
+     * @returns a repository backed by this store's DynamoDB table
+     */
+    getRepository<T extends ModelClass>(model: T): Repository<T>;
+    /**
+     * Return the underlying DynamoRepository for each model this store manages
+     * @returns the repositories
+     */
+    getRepositories(): DynamoRepository<any>[];
+    /**
+     * IAM policy required by the store
+     * @param accountId - AWS account id
+     * @returns the policy statement
+     */
+    getARNPolicy(accountId: string): {
+        Sid: string;
+        Effect: string;
+        Action: string[];
+        Resource: string[];
+    };
+    /**
+     * Delete all items from the managed tables (used in tests)
+     */
+    __clean(): Promise<void>;
+    /**
+     * CloudFormation resources for the table
+     * @param deployer - the deployer requesting the resources
+     * @returns the resources
+     */
+    getCloudFormation(deployer: CloudFormationDeployerInfo): {};
+}
+export default DynamoStore;
+//# sourceMappingURL=dynamodb.service.d.ts.map

package/lib/services/dynamodb.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb.service.d.ts","sourceRoot":"","sources":["../../src/services/dynamodb.service.ts"],"names":[],"mappings":"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"}