@cadenza.io/service 2.12.0 → 2.16.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.
@@ -40,6 +41,52 @@ import Cadenza from '@cadenza.io/service';
 Cadenza.createCadenzaService('MyService'); // Name should start with an uppercase letter and contain no spaces.
 ```
 
+### Creating a frontend runtime
+Frontend mode keeps the same package and distributed primitives, but disables Node-only features such as REST/socket server creation, PostgresActors, and database-service bootstrapping.
+
+```typescript
+import Cadenza from '@cadenza.io/service';
+
+Cadenza.createCadenzaService('BrowserApp', 'Frontend app', {
+  isFrontend: true,
+  bootstrap: {
+    url: 'https://cadenza-db.example.com:5000',
+  },
+});
+```
+
+Frontend bootstrap resolution order is:
+
+1. `options.bootstrap.url`
+2. `globalThis.__CADENZA_RUNTIME__.bootstrapUrl`
+3. `CADENZA_DB_ADDRESS` plus optional `CADENZA_DB_PORT` on the server side
+
+`CADENZA_DB_ADDRESS` now accepts either a full address with port, or a bare host/address when `CADENZA_DB_PORT` is also set.
+
+### SSR inquiries
+For SSR use cases, use the request-scoped bridge for one-off distributed inquiries and pass dehydrated results to the browser runtime.
+
+```typescript
+import {
+  createSSRInquiryBridge,
+  type HydrationOptions,
+} from '@cadenza.io/service';
+
+const bridge = createSSRInquiryBridge({
+  bootstrap: {
+    url: process.env.CADENZA_DB_ADDRESS,
+  },
+});
+
+const users = await bridge.inquire(
+  'users-list',
+  {},
+  { hydrationKey: 'users-list.initial' },
+);
+
+const hydration: HydrationOptions = bridge.dehydrate();
+```
+
 ### Working with distribution
 Distribution is easy with Cadenza. You can delegate the flow by using a DeputyTask, or subscribe to foreign signals by prefixing them with the service name.
 
@@ -62,6 +109,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)