@cadenza.io/service 2.10.0 → 2.12.0

package/README.md

@@ -55,6 +55,18 @@ localTask.doOn('ContextService.process.failed');
 
 For full examples, see this repository or the test suite.
 
+## PostgresActor Documentation
+
+Canonical PostgresActor docs:
+
+- [PostgresActor Guide](./docs/postgres-actor-guide.md)
+- [PostgresActor Reference](./docs/postgres-actor-reference.md)
+
+Workspace mirror (for cross-repo publication):
+
+- [Workspace Guide Mirror](../docs/postgres-actor-guide.md)
+- [Workspace Reference Mirror](../docs/postgres-actor-reference.md)
+
 
 ## Features
 

package/dist/index.d.mts

@@ -57,6 +57,14 @@ declare class DeputyTask extends Task {
 }
 
 type DbOperationType$1 = "query" | "insert" | "update" | "delete";
+type QueryMode = "rows" | "count" | "exists" | "one" | "aggregate";
+type AggregateFunction = "count" | "sum" | "avg" | "min" | "max";
+interface AggregateDefinition {
+    fn: AggregateFunction;
+    field?: string;
+    as?: string;
+    distinct?: boolean;
+}
 type SortDirection = "asc" | "desc";
 interface JoinDefinition {
     on: string;
@@ -88,6 +96,9 @@ interface DbOperationPayload {
     filter?: Record<string, ValueOrList>;
     fields?: string[];
     joins?: Record<string, JoinDefinition>;
+    queryMode?: QueryMode;
+    aggregates?: AggregateDefinition[];
+    groupBy?: string[];
     sort?: Record<string, SortDirection>;
     limit?: number;
     offset?: number;
@@ -434,6 +445,21 @@ interface TableDefinition {
             description?: string;
             input?: SchemaDefinition;
         })[];
+        insert?: (string | {
+            intent: string;
+            description?: string;
+            input?: SchemaDefinition;
+        })[];
+        update?: (string | {
+            intent: string;
+            description?: string;
+            input?: SchemaDefinition;
+        })[];
+        delete?: (string | {
+            intent: string;
+            description?: string;
+            input?: SchemaDefinition;
+        })[];
     };
     initialData?: {
         fields: string[];
@@ -22404,14 +22430,28 @@ declare class CadenzaService {
      */
     static createCadenzaMetaService(serviceName: string, description: string, options?: ServerOptions): void;
     /**
-     * Creates and initializes a database service with the provided name, schema, and configuration options.
-     * This method is not supported in a browser environment and will log a warning if called in such an environment.
+     * Creates and initializes a PostgresActor-backed database service.
+     * This is the canonical API for schema-driven postgres setup in cadenza-service.
      *
-     * @param {string} name - The name of the database service to be created.
-     * @param {DatabaseSchemaDefinition} schema - The schema definition for the database service.
-     * @param {string} [description=""] - An optional description of the database service.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional configuration settings for the database and server.
-     * @return {void} This method does not return a value.
+     * @param {string} name - Logical actor/service name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional human-readable description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Server/database runtime options.
+     * @return {void}
+     */
+    static createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a meta PostgresActor service.
+     *
+     * @param {string} name - Logical actor/service name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server/database options.
+     * @return {void}
+     */
+    static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Legacy compatibility wrapper. Prefer {@link createPostgresActor}.
      */
     static createDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
@@ -22921,4 +22961,4 @@ declare class SignalController {
     constructor();
 }
 
-export { DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };
+export { type AggregateDefinition, type AggregateFunction, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };

package/dist/index.d.ts

@@ -57,6 +57,14 @@ declare class DeputyTask extends Task {
 }
 
 type DbOperationType$1 = "query" | "insert" | "update" | "delete";
+type QueryMode = "rows" | "count" | "exists" | "one" | "aggregate";
+type AggregateFunction = "count" | "sum" | "avg" | "min" | "max";
+interface AggregateDefinition {
+    fn: AggregateFunction;
+    field?: string;
+    as?: string;
+    distinct?: boolean;
+}
 type SortDirection = "asc" | "desc";
 interface JoinDefinition {
     on: string;
@@ -88,6 +96,9 @@ interface DbOperationPayload {
     filter?: Record<string, ValueOrList>;
     fields?: string[];
     joins?: Record<string, JoinDefinition>;
+    queryMode?: QueryMode;
+    aggregates?: AggregateDefinition[];
+    groupBy?: string[];
     sort?: Record<string, SortDirection>;
     limit?: number;
     offset?: number;
@@ -434,6 +445,21 @@ interface TableDefinition {
             description?: string;
             input?: SchemaDefinition;
         })[];
+        insert?: (string | {
+            intent: string;
+            description?: string;
+            input?: SchemaDefinition;
+        })[];
+        update?: (string | {
+            intent: string;
+            description?: string;
+            input?: SchemaDefinition;
+        })[];
+        delete?: (string | {
+            intent: string;
+            description?: string;
+            input?: SchemaDefinition;
+        })[];
     };
     initialData?: {
         fields: string[];
@@ -22404,14 +22430,28 @@ declare class CadenzaService {
      */
     static createCadenzaMetaService(serviceName: string, description: string, options?: ServerOptions): void;
     /**
-     * Creates and initializes a database service with the provided name, schema, and configuration options.
-     * This method is not supported in a browser environment and will log a warning if called in such an environment.
+     * Creates and initializes a PostgresActor-backed database service.
+     * This is the canonical API for schema-driven postgres setup in cadenza-service.
      *
-     * @param {string} name - The name of the database service to be created.
-     * @param {DatabaseSchemaDefinition} schema - The schema definition for the database service.
-     * @param {string} [description=""] - An optional description of the database service.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional configuration settings for the database and server.
-     * @return {void} This method does not return a value.
+     * @param {string} name - Logical actor/service name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional human-readable description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Server/database runtime options.
+     * @return {void}
+     */
+    static createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a meta PostgresActor service.
+     *
+     * @param {string} name - Logical actor/service name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server/database options.
+     * @return {void}
+     */
+    static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Legacy compatibility wrapper. Prefer {@link createPostgresActor}.
      */
     static createDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
@@ -22921,4 +22961,4 @@ declare class SignalController {
     constructor();
 }
 
-export { DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };
+export { type AggregateDefinition, type AggregateFunction, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };