@twin.org/entity-storage-connector-postgresql 0.0.1-next.21

package/dist/types/postgreSqlEntityStorageConnector.d.ts

@@ -0,0 +1,94 @@
+import { type EntityCondition, type IEntitySchema, SortDirection } from "@twin.org/entity";
+import type { IEntityStorageConnector } from "@twin.org/entity-storage-models";
+import type { IPostgreSqlEntityStorageConnectorConstructorOptions } from "./models/IPostgreSqlEntityStorageConnectorConstructorOptions";
+/**
+ * Class for performing entity storage operations using ql.
+ */
+export declare class PostgreSqlEntityStorageConnector<T = unknown> implements IEntityStorageConnector<T> {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of PostgreSqlEntityStorageConnector.
+     * @param options The options for the connector.
+     */
+    constructor(options: IPostgreSqlEntityStorageConnectorConstructorOptions);
+    /**
+     * Initialize the PostgreSql environment.
+     * @param nodeLoggingConnectorType Optional type of the logging connector.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    bootstrap(nodeLoggingConnectorType?: string): Promise<boolean>;
+    /**
+     * Get the schema for the entities.
+     * @returns The schema for the entities.
+     */
+    getSchema(): IEntitySchema;
+    /**
+     * Get an entity from PostgreSql.
+     * @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.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The object if it can be found or undefined.
+     */
+    get(id: string, secondaryIndex?: keyof T, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<T | undefined>;
+    /**
+     * Set an entity.
+     * @param entity The entity to set.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The id of the entity.
+     */
+    set(entity: T, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<void>;
+    /**
+     * Remove the entity.
+     * @param id The id of the entity to remove.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns Nothing.
+     */
+    remove(id: string, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): 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<{
+        entities: Partial<T>[];
+        cursor?: string;
+    }>;
+    /**
+     * Drop the table.
+     * @returns Nothing.
+     */
+    tableDrop(): Promise<void>;
+    /**
+     * Map entity schema properties to SQL properties.
+     * @param entitySchema The schema of the entity.
+     * @returns The SQL properties as a string.
+     * @throws GeneralError if the entity properties do not exist.
+     */
+    private mapPostgreSqlProperties;
+    /**
+     * Validate that the entity matches the schema.
+     * @param entity The entity to validate.
+     * @throws GeneralError if the entity schema properties are undefined or if the entity does not match the schema.
+     */
+    private entitySqlVerification;
+}

package/docs/changelog.md

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

package/docs/examples.md

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

package/docs/reference/classes/PostgreSqlEntityStorageConnector.md

@@ -0,0 +1,254 @@
+# Class: PostgreSqlEntityStorageConnector\<T\>
+
+Class for performing entity storage operations using ql.
+
+## Type Parameters
+
+• **T** = `unknown`
+
+## Implements
+
+- `IEntityStorageConnector`\<`T`\>
+
+## Constructors
+
+### new PostgreSqlEntityStorageConnector()
+
+> **new PostgreSqlEntityStorageConnector**\<`T`\>(`options`): [`PostgreSqlEntityStorageConnector`](PostgreSqlEntityStorageConnector.md)\<`T`\>
+
+Create a new instance of PostgreSqlEntityStorageConnector.
+
+#### Parameters
+
+##### options
+
+[`IPostgreSqlEntityStorageConnectorConstructorOptions`](../interfaces/IPostgreSqlEntityStorageConnectorConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+[`PostgreSqlEntityStorageConnector`](PostgreSqlEntityStorageConnector.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`\>
+
+Initialize the PostgreSql environment.
+
+#### Parameters
+
+##### nodeLoggingConnectorType?
+
+`string`
+
+Optional type of the logging connector.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+A promise that resolves to a boolean indicating success.
+
+#### Implementation of
+
+`IEntityStorageConnector.bootstrap`
+
+***
+
+### getSchema()
+
+> **getSchema**(): `IEntitySchema`
+
+Get the schema for the entities.
+
+#### Returns
+
+`IEntitySchema`
+
+The schema for the entities.
+
+#### Implementation of
+
+`IEntityStorageConnector.getSchema`
+
+***
+
+### get()
+
+> **get**(`id`, `secondaryIndex`?, `conditions`?): `Promise`\<`undefined` \| `T`\>
+
+Get an entity from PostgreSql.
+
+#### 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.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`undefined` \| `T`\>
+
+The object if it can be found or undefined.
+
+#### Implementation of
+
+`IEntityStorageConnector.get`
+
+***
+
+### set()
+
+> **set**(`entity`, `conditions`?): `Promise`\<`void`\>
+
+Set an entity.
+
+#### Parameters
+
+##### entity
+
+`T`
+
+The entity to set.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+The id of the entity.
+
+#### Implementation of
+
+`IEntityStorageConnector.set`
+
+***
+
+### remove()
+
+> **remove**(`id`, `conditions`?): `Promise`\<`void`\>
+
+Remove the entity.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the entity to remove.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageConnector.remove`
+
+***
+
+### query()
+
+> **query**(`conditions`?, `sortProperties`?, `properties`?, `cursor`?, `pageSize`?): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor`: `string`; \}\>
+
+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`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor`: `string`; \}\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+#### Implementation of
+
+`IEntityStorageConnector.query`
+
+***
+
+### tableDrop()
+
+> **tableDrop**(): `Promise`\<`void`\>
+
+Drop the table.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.

package/docs/reference/index.md

@@ -0,0 +1,10 @@
+# @twin.org/entity-storage-connector-postgresql
+
+## Classes
+
+- [PostgreSqlEntityStorageConnector](classes/PostgreSqlEntityStorageConnector.md)
+
+## Interfaces
+
+- [IPostgreSqlEntityStorageConnectorConfig](interfaces/IPostgreSqlEntityStorageConnectorConfig.md)
+- [IPostgreSqlEntityStorageConnectorConstructorOptions](interfaces/IPostgreSqlEntityStorageConnectorConstructorOptions.md)

package/docs/reference/interfaces/IPostgreSqlEntityStorageConnectorConfig.md

@@ -0,0 +1,51 @@
+# Interface: IPostgreSqlEntityStorageConnectorConfig
+
+Configuration for the PostgreSql Entity Storage Connector.
+
+## Properties
+
+### host
+
+> **host**: `string`
+
+The host for the PostgreSql instance.
+
+***
+
+### port?
+
+> `optional` **port**: `number`
+
+The port for the PostgreSql instance.
+
+***
+
+### user
+
+> **user**: `string`
+
+The user for the PostgreSql instance.
+
+***
+
+### password
+
+> **password**: `string`
+
+The password for the PostgreSql instance.
+
+***
+
+### database
+
+> **database**: `string`
+
+The name of the database to be used.
+
+***
+
+### tableName
+
+> **tableName**: `string`
+
+The name of the table to be used.

package/docs/reference/interfaces/IPostgreSqlEntityStorageConnectorConstructorOptions.md

@@ -0,0 +1,33 @@
+# Interface: IPostgreSqlEntityStorageConnectorConstructorOptions
+
+The options for the PostgreSql entity storage connector constructor.
+
+## Properties
+
+### entitySchema
+
+> **entitySchema**: `string`
+
+The schema for the entity.
+
+***
+
+### loggingConnectorType?
+
+> `optional` **loggingConnectorType**: `string`
+
+The type of logging connector to use.
+
+#### Default
+
+```ts
+logging
+```
+
+***
+
+### config
+
+> **config**: [`IPostgreSqlEntityStorageConnectorConfig`](IPostgreSqlEntityStorageConnectorConfig.md)
+
+The configuration for the connector.

package/locales/en.json

@@ -0,0 +1,21 @@
+{
+	"info": {
+		"postgreSqlEntityStorageConnector": {
+			"databaseCreating": "Database \"{databaseName}\" creating",
+			"databaseExists": "Database \"{databaseName}\" created or it already exists",
+			"tableExists": "Database \"{tableName}\" created or it already exists"
+		}
+	},
+	"error": {
+		"postgreSqlEntityStorageConnector": {
+			"setFailed": "Unable to set entity \"{id}\"",
+			"getFailed": "Unable to get entity \"{id}\"",
+			"removeFailed": "Unable to remove entity \"{id}\"",
+			"queryFailed": "The query failed",
+			"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,42 @@
+{
+	"name": "@twin.org/entity-storage-connector-postgresql",
+	"version": "0.0.1-next.21",
+	"description": "Entity Storage connector implementation using PostgreSql storage",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/twinfoundation/entity-storage.git",
+		"directory": "packages/entity-storage-connector-postgresql"
+	},
+	"author": "adrian.sanchez.sequeira@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"dependencies": {
+		"@twin.org/core": "next",
+		"@twin.org/entity": "next",
+		"@twin.org/entity-storage-models": "0.0.1-next.21",
+		"@twin.org/logging-models": "next",
+		"@twin.org/nameof": "next",
+		"postgres": "^3.4.5"
+	},
+	"main": "./dist/cjs/index.cjs",
+	"module": "./dist/esm/index.mjs",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"require": "./dist/cjs/index.cjs",
+			"import": "./dist/esm/index.mjs"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/cjs",
+		"dist/esm",
+		"dist/types",
+		"locales",
+		"docs"
+	]
+}