@cadenza.io/service 2.12.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.
@@ -62,6 +63,11 @@ 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)

package/dist/index.d.mts

@@ -507,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.
@@ -22430,28 +22431,28 @@ declare class CadenzaService {
      */
     static createCadenzaMetaService(serviceName: string, description: string, options?: ServerOptions): void;
     /**
-     * Creates and initializes a PostgresActor-backed database service.
-     * This is the canonical API for schema-driven postgres setup in cadenza-service.
+     * Creates and initializes a specialized PostgresActor.
+     * This is actor-only and does not create or register a network service.
      *
-     * @param {string} name - Logical actor/service name.
+     * @param {string} name - Logical PostgresActor name.
      * @param {DatabaseSchemaDefinition} schema - Database schema definition.
-     * @param {string} [description=""] - Optional human-readable description.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Server/database runtime options.
+     * @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 service.
+     * Creates a meta PostgresActor.
      *
-     * @param {string} name - Logical actor/service name.
+     * @param {string} name - Logical PostgresActor name.
      * @param {DatabaseSchemaDefinition} schema - Database schema definition.
      * @param {string} [description=""] - Optional description.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server/database options.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional actor/database options.
      * @return {void}
      */
     static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
-     * Legacy compatibility wrapper. Prefer {@link createPostgresActor}.
+     * 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;
     /**
@@ -22464,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>;
     /**
@@ -22758,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;
     /**

package/dist/index.d.ts

@@ -507,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.
@@ -22430,28 +22431,28 @@ declare class CadenzaService {
      */
     static createCadenzaMetaService(serviceName: string, description: string, options?: ServerOptions): void;
     /**
-     * Creates and initializes a PostgresActor-backed database service.
-     * This is the canonical API for schema-driven postgres setup in cadenza-service.
+     * Creates and initializes a specialized PostgresActor.
+     * This is actor-only and does not create or register a network service.
      *
-     * @param {string} name - Logical actor/service name.
+     * @param {string} name - Logical PostgresActor name.
      * @param {DatabaseSchemaDefinition} schema - Database schema definition.
-     * @param {string} [description=""] - Optional human-readable description.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Server/database runtime options.
+     * @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 service.
+     * Creates a meta PostgresActor.
      *
-     * @param {string} name - Logical actor/service name.
+     * @param {string} name - Logical PostgresActor name.
      * @param {DatabaseSchemaDefinition} schema - Database schema definition.
      * @param {string} [description=""] - Optional description.
-     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server/database options.
+     * @param {ServerOptions & DatabaseOptions} [options={}] - Optional actor/database options.
      * @return {void}
      */
     static createMetaPostgresActor(name: string, schema: DatabaseSchemaDefinition, description?: string, options?: ServerOptions & DatabaseOptions): void;
     /**
-     * Legacy compatibility wrapper. Prefer {@link createPostgresActor}.
+     * 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;
     /**
@@ -22464,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>;
     /**
@@ -22758,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;
     /**