@cadenza.io/service 2.11.0 → 2.15.0

package/README.md

@@ -16,7 +16,8 @@ This repository (@Cadenza.io/service) is an extension of the core package, provi
 
 The service package provides everything in the core package plus the following:
 - **Service Extension**: A Service exposes the local graphs and signals to other Services in the system and enables them to interact with tasks and signals across other Services in the system via socket and/or REST.
-- **Database Service Extension**: A Database Service takes a schema and auto generates the necessary tasks and signals to interact with that database using the cadenza model. It exposes those tasks using by creating a Service.
+- **PostgresActor Extension**: A PostgresActor is a specialized actor that owns a Postgres pool, applies schema setup, and auto generates database tasks and intents without creating a network service.
+- **Database Service Extension**: A Database Service is the higher-level helper that first creates a PostgresActor and then creates a Service that exposes those generated database tasks.
 - **CadenzaDB compatibility**: A service can connect to the official CadenzaDB service and will automatically sync realtime data for introspection and visualization.
 
 There is no need to install the core package separately. Instead, install the service package, which includes everything in the core package plus the distributed extensions.
@@ -55,6 +56,23 @@ 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)
+
+High-level database service helper APIs:
+
+- `Cadenza.createDatabaseService(...)`
+- `Cadenza.createMetaDatabaseService(...)`
+
+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[];
@@ -481,6 +507,7 @@ interface DatabaseOptions {
     databaseType?: "postgres";
     databaseName?: string;
     poolSize?: number;
+    ownerServiceName?: string | null;
 }
 /**
  * The CadenzaService class serves as a central service layer providing various utility methods for managing tasks, signals, logging, and service interactions.
@@ -22404,14 +22431,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 specialized PostgresActor.
+     * This is actor-only and does not create or register a network 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 PostgresActor name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional human-readable actor description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Actor/database runtime options.
+     * @return {void}
+     */
+    static createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a meta PostgresActor.
+     *
+     * @param {string} name - Logical PostgresActor name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional actor/database options.
+     * @return {void}
+     */
+    static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a dedicated database service by composing a PostgresActor and a Cadenza service.
      */
     static createDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
@@ -22424,6 +22465,9 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    private static normalizePostgresActorOptions;
+    private static normalizeDatabaseServiceOptions;
+    private static registerDatabaseServiceBridgeTask;
     static createActor<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
     static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
@@ -22718,14 +22762,14 @@ declare class CadenzaService {
      */
     static createEphemeralTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
-     * Creates an ephemeral meta task with the specified name, function, description, and options.
+     * Creates an ephemeral meta-task with the specified name, function, description, and options.
      * See {@link createEphemeralTask} and {@link createMetaTask} for more details.
      *
      * @param {string} name - The name of the task to be created.
      * @param {TaskFunction} func - The function to be executed as part of the task.
      * @param {string} [description] - An optional description of the task.
      * @param {TaskOptions & EphemeralTaskOptions} [options={}] - Additional options for configuring the task.
-     * @return {EphemeralTask} The created ephemeral meta task.
+     * @return {EphemeralTask} The created ephemeral meta-task.
      */
     static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
@@ -22921,4 +22965,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[];
@@ -481,6 +507,7 @@ interface DatabaseOptions {
     databaseType?: "postgres";
     databaseName?: string;
     poolSize?: number;
+    ownerServiceName?: string | null;
 }
 /**
  * The CadenzaService class serves as a central service layer providing various utility methods for managing tasks, signals, logging, and service interactions.
@@ -22404,14 +22431,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 specialized PostgresActor.
+     * This is actor-only and does not create or register a network 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 PostgresActor name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional human-readable actor description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Actor/database runtime options.
+     * @return {void}
+     */
+    static createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a meta PostgresActor.
+     *
+     * @param {string} name - Logical PostgresActor name.
+     * @param {DatabaseSchemaDefinition} schema - Database schema definition.
+     * @param {string} [description=""] - Optional description.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional actor/database options.
+     * @return {void}
+     */
+    static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    /**
+     * Creates a dedicated database service by composing a PostgresActor and a Cadenza service.
      */
     static createDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
@@ -22424,6 +22465,9 @@ declare class CadenzaService {
      * @return {void} - This method does not return a value.
      */
     static createMetaDatabaseService(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
+    private static normalizePostgresActorOptions;
+    private static normalizeDatabaseServiceOptions;
+    private static registerDatabaseServiceBridgeTask;
     static createActor<D extends Record<string, any> = AnyObject, R = AnyObject>(spec: ActorSpec<D, R>, options?: ActorFactoryOptions): Actor<D, R>;
     static createActorFromDefinition<D extends Record<string, any> = AnyObject, R = AnyObject>(definition: ActorDefinition<D, R>, options?: ActorFactoryOptions<D, R>): Actor<D, R>;
     /**
@@ -22718,14 +22762,14 @@ declare class CadenzaService {
      */
     static createEphemeralTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
-     * Creates an ephemeral meta task with the specified name, function, description, and options.
+     * Creates an ephemeral meta-task with the specified name, function, description, and options.
      * See {@link createEphemeralTask} and {@link createMetaTask} for more details.
      *
      * @param {string} name - The name of the task to be created.
      * @param {TaskFunction} func - The function to be executed as part of the task.
      * @param {string} [description] - An optional description of the task.
      * @param {TaskOptions & EphemeralTaskOptions} [options={}] - Additional options for configuring the task.
-     * @return {EphemeralTask} The created ephemeral meta task.
+     * @return {EphemeralTask} The created ephemeral meta-task.
      */
     static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
@@ -22921,4 +22965,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 };