@twin.org/entity-storage-connector-postgresql 0.10.1-next.5 → 0.10.1-next.7

package/dist/types/postgreSqlEntityStorageConnector.d.ts

@@ -1,7 +1,7 @@
 import { type IHealth, type IHealthProviderComponent } from "@twin.org/api-models";
 import { type IContextIds } from "@twin.org/context";
 import { type EntityCondition, type IEntitySchema, SortDirection } from "@twin.org/entity";
-import { type IEntityStorageMigrationConnector, type IMigrationOptions } from "@twin.org/entity-storage-models";
+import { type IEntityStorageConnector, type IEntityStorageJoinOptions, type IEntityStorageMigrationConnector, type IMigrationOptions } from "@twin.org/entity-storage-models";
 import type { IPostgreSqlEntityStorageConnectorConstructorOptions } from "./models/IPostgreSqlEntityStorageConnectorConstructorOptions.js";
 /**
  * Class for performing entity storage operations using ql.
@@ -146,6 +146,27 @@ export declare class PostgreSqlEntityStorageConnector<T = unknown> implements IE
         entities: Partial<T>[];
         cursor?: string;
     }>;
+    /**
+     * Find all the entities which match the conditions, attaching to each one the entities from a
+     * second storage connector whose join property matches. The join behaves like a left join by
+     * default, a primary entity with no matches is still returned with an empty joined list, unless
+     * joinRequired asks for an inner join and those entities are left out altogether. Both connectors
+     * must be PostgreSQL connectors reading from the same database so the work can be done in a
+     * single statement.
+     * @param joinConnector The connector holding the entities to join to.
+     * @param joinOptions The properties to join on, the conditions, sort order, projection and
+     * paging for the primary entities, the optional grouping and group conditions, and the optional
+     * conditions, sort order and projection for the joined entities.
+     * @returns All the entities for the storage matching the conditions with their joined entities,
+     * and a cursor which can be used to request more entities.
+     * @throws GeneralError if the join connector does not read from the same server and database.
+     */
+    queryJoin<U>(joinConnector: IEntityStorageConnector<U>, joinOptions: IEntityStorageJoinOptions<T, U>): Promise<{
+        entities: (Partial<T> & {
+            joined: Partial<U>[];
+        })[];
+        cursor?: string;
+    }>;
     /**
      * Count all the entities which match the conditions.
      * @param conditions The optional conditions to match for the entities.

package/docs/changelog.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.10.1-next.7](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.6...entity-storage-connector-postgresql-v0.10.1-next.7) (2026-09-22)
+
+
+### Bug Fixes
+
+* project properties in common group join ([b90389d](https://github.com/iotaledger/twin-entity-storage/commit/b90389dd7df593b560faf2299e912c25a66bf6ee))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.6 to 0.10.1-next.7
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.6 to 0.10.1-next.7
+
+## [0.10.1-next.6](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.5...entity-storage-connector-postgresql-v0.10.1-next.6) (2026-09-21)
+
+
+### Features
+
+* join and group ([#295](https://github.com/iotaledger/twin-entity-storage/issues/295)) ([e0103b3](https://github.com/iotaledger/twin-entity-storage/commit/e0103b3af5d9d0d37d4f590c6f31993d2c7e6508))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/entity-storage-models bumped from 0.10.1-next.5 to 0.10.1-next.6
+  * devDependencies
+    * @twin.org/entity-storage-connector-memory bumped from 0.10.1-next.5 to 0.10.1-next.6
+
 ## [0.10.1-next.5](https://github.com/iotaledger/twin-entity-storage/compare/entity-storage-connector-postgresql-v0.10.1-next.4...entity-storage-connector-postgresql-v0.10.1-next.5) (2026-09-18)
 
 

package/docs/reference/classes/PostgreSqlEntityStorageConnector.md

@@ -556,6 +556,56 @@ and a cursor which can be used to request more entities.
 
 ***
 
+### queryJoin() {#queryjoin}
+
+> **queryJoin**\<`U`\>(`joinConnector`, `joinOptions`): `Promise`\<\{ `entities`: `Partial`\<`T`\> & `object`[]; `cursor?`: `string`; \}\>
+
+Find all the entities which match the conditions, attaching to each one the entities from a
+second storage connector whose join property matches. The join behaves like a left join by
+default, a primary entity with no matches is still returned with an empty joined list, unless
+joinRequired asks for an inner join and those entities are left out altogether. Both connectors
+must be PostgreSQL connectors reading from the same database so the work can be done in a
+single statement.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### joinConnector
+
+`IEntityStorageConnector`\<`U`\>
+
+The connector holding the entities to join to.
+
+##### joinOptions
+
+`IEntityStorageJoinOptions`\<`T`, `U`\>
+
+The properties to join on, the conditions, sort order, projection and
+paging for the primary entities, the optional grouping and group conditions, and the optional
+conditions, sort order and projection for the joined entities.
+
+#### Returns
+
+`Promise`\<\{ `entities`: `Partial`\<`T`\> & `object`[]; `cursor?`: `string`; \}\>
+
+All the entities for the storage matching the conditions with their joined entities,
+and a cursor which can be used to request more entities.
+
+#### Throws
+
+GeneralError if the join connector does not read from the same server and database.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.queryJoin`
+
+***
+
 ### count() {#count}
 
 > **count**(`conditions?`): `Promise`\<`number`\>

package/locales/en.json

@@ -25,6 +25,8 @@
 			"getFailed": "Unable to get entity \"{id}\"",
 			"removeFailed": "Unable to remove entity \"{id}\"",
 			"queryFailed": "The query failed",
+			"queryJoinFailed": "The join query failed",
+			"joinConnectorMismatch": "The join connector must be a PostgreSQL connector reading from the same server and database \"{database}\"",
 			"comparisonNotSupported": "Comparison operator \"{comparison}\" is not supported",
 			"conditionalNotSupported": "Conditional operator \"{operator}\" is not supported",
 			"entitySchemaPropertiesUndefined": "The entity schema properties are undefined",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-connector-postgresql",
-	"version": "0.10.1-next.5",
+	"version": "0.10.1-next.7",
 	"description": "PostgreSQL connector for relational persistence and advanced SQL features.",
 	"repository": {
 		"type": "git",
@@ -18,7 +18,7 @@
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
-		"@twin.org/entity-storage-models": "0.10.1-next.5",
+		"@twin.org/entity-storage-models": "0.10.1-next.7",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"postgres": "3.4.9"