@twin.org/entity-storage-connector-dynamodb 0.0.1-next.2

package/dist/types/dynamoDbEntityStorageConnector.d.ts

@@ -0,0 +1,77 @@
+import { type EntityCondition, type SortDirection } from "@twin.org/entity";
+import type { IEntityStorageConnector } from "@twin.org/entity-storage-models";
+import type { IDynamoDbEntityStorageConnectorConfig } from "./models/IDynamoDbEntityStorageConnectorConfig";
+/**
+ * Class for performing entity storage operations using Dynamo DB.
+ */
+export declare class DynamoDbEntityStorageConnector<T = unknown> implements IEntityStorageConnector<T> {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of DynamoDbEntityStorageConnector.
+     * @param options The options for the connector.
+     * @param options.entitySchema The schema for the entity.
+     * @param options.loggingConnectorType The type of logging connector to use, defaults to no logging.
+     * @param options.config The configuration for the connector.
+     */
+    constructor(options: {
+        entitySchema: string;
+        loggingConnectorType?: string;
+        config: IDynamoDbEntityStorageConnectorConfig;
+    });
+    /**
+     * Bootstrap the component by creating and initializing any resources it needs.
+     * @param nodeLoggingConnectorType The node logging connector type, defaults to "node-logging".
+     * @returns True if the bootstrapping process was successful.
+     */
+    bootstrap(nodeLoggingConnectorType?: string): Promise<boolean>;
+    /**
+     * Get an entity.
+     * @param id The id of the entity to get, or the index value if secondaryIndex is set.
+     * @param secondaryIndex Get the item using a secondary index.
+     * @returns The object if it can be found or undefined.
+     */
+    get(id: string, secondaryIndex?: keyof T): Promise<T | undefined>;
+    /**
+     * Set an entity.
+     * @param entity The entity to set.
+     * @returns The id of the entity.
+     */
+    set(entity: T): Promise<void>;
+    /**
+     * Remove the entity.
+     * @param id The id of the entity to remove.
+     * @returns Nothing.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Find all the entities which match the conditions.
+     * @param conditions The conditions to match for the entities.
+     * @param sortProperties The optional sort order.
+     * @param properties The optional properties to return, defaults to all.
+     * @param cursor The cursor to request the next page of entities.
+     * @param pageSize The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     */
+    query(conditions?: EntityCondition<T>, sortProperties?: {
+        property: keyof T;
+        sortDirection: SortDirection;
+    }[], properties?: (keyof T)[], cursor?: string, pageSize?: number): Promise<{
+        /**
+         * The entities, which can be partial if a limited keys list was provided.
+         */
+        entities: Partial<T>[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    }>;
+    /**
+     * Delete the table.
+     * @returns Nothing.
+     */
+    tableDelete(): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./dynamoDbEntityStorageConnector";
+export * from "./models/IDynamoDbEntityStorageConnectorConfig";

package/dist/types/models/IDynamoDbEntityStorageConnectorConfig.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration for the Dynamo DB Entity Storage Connector.
+ */
+export interface IDynamoDbEntityStorageConnectorConfig {
+    /**
+     * The region for the AWS connection.
+     */
+    region: string;
+    /**
+     * The AWS access key.
+     */
+    accessKeyId: string;
+    /**
+     * The AWS secret access key.
+     */
+    secretAccessKey: string;
+    /**
+     * The name of the table for the storage.
+     */
+    tableName: string;
+    /**
+     * AWS endpoint, not usually required but could be used for local DynamoDB instance e.g. http://localhost:8000.
+     */
+    endpoint?: string;
+}

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/entity-storage-connector-dynamodb - Changelog
+
+## v0.0.1-next.2
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/entity-storage-connector-dynamodb - Examples

package/docs/reference/classes/DynamoDbEntityStorageConnector.md

@@ -0,0 +1,220 @@
+# Class: DynamoDbEntityStorageConnector\<T\>
+
+Class for performing entity storage operations using Dynamo DB.
+
+## Type Parameters
+
+• **T** = `unknown`
+
+## Implements
+
+- `IEntityStorageConnector`\<`T`\>
+
+## Constructors
+
+### new DynamoDbEntityStorageConnector()
+
+> **new DynamoDbEntityStorageConnector**\<`T`\>(`options`): [`DynamoDbEntityStorageConnector`](DynamoDbEntityStorageConnector.md)\<`T`\>
+
+Create a new instance of DynamoDbEntityStorageConnector.
+
+#### Parameters
+
+• **options**
+
+The options for the connector.
+
+• **options.entitySchema**: `string`
+
+The schema for the entity.
+
+• **options.loggingConnectorType?**: `string`
+
+The type of logging connector to use, defaults to no logging.
+
+• **options.config**: [`IDynamoDbEntityStorageConnectorConfig`](../interfaces/IDynamoDbEntityStorageConnectorConfig.md)
+
+The configuration for the connector.
+
+#### Returns
+
+[`DynamoDbEntityStorageConnector`](DynamoDbEntityStorageConnector.md)\<`T`\>
+
+## Properties
+
+### CLASS\_NAME
+
+> `readonly` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+#### Implementation of
+
+`IEntityStorageConnector.CLASS_NAME`
+
+## Methods
+
+### bootstrap()
+
+> **bootstrap**(`nodeLoggingConnectorType`?): `Promise`\<`boolean`\>
+
+Bootstrap the component by creating and initializing any resources it needs.
+
+#### Parameters
+
+• **nodeLoggingConnectorType?**: `string`
+
+The node logging connector type, defaults to "node-logging".
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the bootstrapping process was successful.
+
+#### Implementation of
+
+`IEntityStorageConnector.bootstrap`
+
+***
+
+### get()
+
+> **get**(`id`, `secondaryIndex`?): `Promise`\<`undefined` \| `T`\>
+
+Get an entity.
+
+#### Parameters
+
+• **id**: `string`
+
+The id of the entity to get, or the index value if secondaryIndex is set.
+
+• **secondaryIndex?**: keyof `T`
+
+Get the item using a secondary index.
+
+#### Returns
+
+`Promise`\<`undefined` \| `T`\>
+
+The object if it can be found or undefined.
+
+#### Implementation of
+
+`IEntityStorageConnector.get`
+
+***
+
+### set()
+
+> **set**(`entity`): `Promise`\<`void`\>
+
+Set an entity.
+
+#### Parameters
+
+• **entity**: `T`
+
+The entity to set.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+The id of the entity.
+
+#### Implementation of
+
+`IEntityStorageConnector.set`
+
+***
+
+### remove()
+
+> **remove**(`id`): `Promise`\<`void`\>
+
+Remove the entity.
+
+#### Parameters
+
+• **id**: `string`
+
+The id of the entity to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageConnector.remove`
+
+***
+
+### query()
+
+> **query**(`conditions`?, `sortProperties`?, `properties`?, `cursor`?, `pageSize`?): `Promise`\<`object`\>
+
+Find all the entities which match the conditions.
+
+#### Parameters
+
+• **conditions?**: `EntityCondition`\<`T`\>
+
+The conditions to match for the entities.
+
+• **sortProperties?**: `object`[]
+
+The optional sort order.
+
+• **properties?**: keyof `T`[]
+
+The optional properties to return, defaults to all.
+
+• **cursor?**: `string`
+
+The cursor to request the next page of entities.
+
+• **pageSize?**: `number`
+
+The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
+
+#### Returns
+
+`Promise`\<`object`\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+##### entities
+
+> **entities**: `Partial`\<`T`\>[]
+
+The entities, which can be partial if a limited keys list was provided.
+
+##### cursor?
+
+> `optional` **cursor**: `string`
+
+An optional cursor, when defined can be used to call find to get more entities.
+
+#### Implementation of
+
+`IEntityStorageConnector.query`
+
+***
+
+### tableDelete()
+
+> **tableDelete**(): `Promise`\<`void`\>
+
+Delete the table.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.

package/docs/reference/index.md

@@ -0,0 +1,9 @@
+# @twin.org/entity-storage-connector-dynamodb
+
+## Classes
+
+- [DynamoDbEntityStorageConnector](classes/DynamoDbEntityStorageConnector.md)
+
+## Interfaces
+
+- [IDynamoDbEntityStorageConnectorConfig](interfaces/IDynamoDbEntityStorageConnectorConfig.md)

package/docs/reference/interfaces/IDynamoDbEntityStorageConnectorConfig.md

@@ -0,0 +1,43 @@
+# Interface: IDynamoDbEntityStorageConnectorConfig
+
+Configuration for the Dynamo DB Entity Storage Connector.
+
+## Properties
+
+### region
+
+> **region**: `string`
+
+The region for the AWS connection.
+
+***
+
+### accessKeyId
+
+> **accessKeyId**: `string`
+
+The AWS access key.
+
+***
+
+### secretAccessKey
+
+> **secretAccessKey**: `string`
+
+The AWS secret access key.
+
+***
+
+### tableName
+
+> **tableName**: `string`
+
+The name of the table for the storage.
+
+***
+
+### endpoint?
+
+> `optional` **endpoint**: `string`
+
+AWS endpoint, not usually required but could be used for local DynamoDB instance e.g. http://localhost:8000.

package/locales/en.json

@@ -0,0 +1,23 @@
+{
+	"info": {
+		"dynamoDbEntityStorageConnector": {
+			"tableCreating": "Creating table \"{tableName}\"",
+			"tableCreated": "Created table \"{tableName}\"",
+			"tableExists": "Skipping create table \"{tableName}\" as it already exists"
+		}
+	},
+	"error": {
+		"dynamoDbEntityStorageConnector": {
+			"tableCreateFailed": "Creating table \"{tableName}\" failed",
+			"tableDoesNotExist": "Table \"{tableName}\" does not exist",
+			"setFailed": "Unable to set entity \"{id}\"",
+			"getFailed": "Unable to get entity \"{id}\"",
+			"removeFailed": "Unable to remove entity \"{id}\"",
+			"queryFailed": "The query failed when issuing the following command \"{sql}\"",
+			"comparisonNotSupported": "Comparison operator \"{comparison}\" is not supported",
+			"conditionalNotSupported": "Conditional operator \"{operator}\" is not supported",
+			"sortSingle": "You can only sort by a single property",
+			"sortNotIndexed": "The property \"{property}\" is not indexed and cannot be used for sorting"
+		}
+	}
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+	"name": "@twin.org/entity-storage-connector-dynamodb",
+	"version": "0.0.1-next.2",
+	"description": "Entity Storage connector implementation using DynamoDb storage",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/twinfoundation/entity-storage.git",
+		"directory": "packages/entity-storage-connector-dynamodb"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"scripts": {
+		"clean": "rimraf dist coverage docs/reference",
+		"build": "tspc",
+		"test": "vitest --run --config ./vitest.config.ts --no-cache",
+		"coverage": "vitest --run --coverage --config ./vitest.config.ts --no-cache",
+		"bundle:esm": "rollup --config rollup.config.mjs --environment MODULE:esm",
+		"bundle:cjs": "rollup --config rollup.config.mjs --environment MODULE:cjs",
+		"bundle": "npm run bundle:esm && npm run bundle:cjs",
+		"docs:clean": "rimraf docs/reference",
+		"docs:generate": "typedoc",
+		"docs": "npm run docs:clean && npm run docs:generate",
+		"dist": "npm run clean && npm run build && npm run test && npm run bundle && npm run docs"
+	},
+	"dependencies": {
+		"@twin.org/core": "next",
+		"@twin.org/entity": "next",
+		"@twin.org/nameof": "next",
+		"@twin.org/entity-storage-models": "0.0.1-next.2",
+		"@twin.org/logging-models": "next",
+		"@aws-sdk/client-dynamodb": "3.651",
+		"@aws-sdk/lib-dynamodb": "3.651",
+		"@aws-sdk/util-dynamodb": "3.651"
+	},
+	"devDependencies": {
+		"@twin.org/entity-storage-connector-memory": "0.0.1-next.2",
+		"@twin.org/logging-connector-entity-storage": "next",
+		"@twin.org/nameof-transformer": "next",
+		"@vitest/coverage-v8": "2.1.1",
+		"copyfiles": "2.4.1",
+		"dotenv": "16.4.5",
+		"rimraf": "6.0.1",
+		"rollup": "4.21.3",
+		"rollup-plugin-copy": "3.5.0",
+		"rollup-plugin-typescript2": "0.36.0",
+		"ts-patch": "3.2.1",
+		"typedoc": "0.26.7",
+		"typedoc-plugin-markdown": "4.2.7",
+		"typescript": "5.6.2",
+		"vitest": "2.1.1"
+	},
+	"main": "./dist/cjs/index.cjs",
+	"module": "./dist/esm/index.mjs",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"require": "./dist/cjs/index.cjs",
+			"import": "./dist/esm/index.mjs",
+			"types": "./dist/types/index.d.ts"
+		},
+		"./locales": "./locales"
+	},
+	"files": [
+		"dist/cjs",
+		"dist/esm",
+		"dist/types",
+		"locales",
+		"docs"
+	]
+}