@empyria/restate 0.1.3 → 0.1.4

package/README.md

@@ -43,12 +43,13 @@ import { checkServiceHandler } from '@empyria/restate/lib/Admin.js'
 
 ## Modules
 
-| Module                                   | Purpose                                                                                                                                                                                                       |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [lib/Admin.js](./lib/Admin.js)           | Restate Admin API client — service/handler discovery, deployment registration and teardown, workflow/message dispatch, `defineWorkflow`/`defineService`/`defineObject`/`definePubsub` construct definers, and `setupRestate` for wiring up an endpoint with health checks and graceful shutdown. |
-| [lib/Caller.js](./lib/Caller.js)         | `CallerServiceDef` — a generic Restate service that dispatches a call to any handler on any other service by name, for when the target isn't known at compile time.                                           |
-| [lib/Cron.js](./lib/Cron.js)             | `cronJobInitiator`/`cronJob` — Restate services implementing cron-driven, replay-safe recurring job scheduling on top of `croner`.                                                                            |
-| [lib/Validation.js](./lib/Validation.js) | `withValidation` — wraps a workflow handler with input/output JSON schema validation via `@empyria/common`.                                                                                                   |
+| Module                                   | Purpose                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [lib/Admin.js](./lib/Admin.js)           | Restate Admin API client — service/handler discovery, deployment registration and teardown, workflow/message dispatch, `defineWorkflow`/`defineService`/`defineObject` construct definers, and `setupRestate` for wiring up an endpoint with health checks and graceful shutdown.                      |
+| [lib/Caller.js](./lib/Caller.js)         | `CallerServiceDef` — a generic Restate service that dispatches a call to any handler on any other service by name, for when the target isn't known at compile time.                                                                                                                                    |
+| [lib/Cron.js](./lib/Cron.js)             | `cronJobInitiator`/`cronJob` — Restate services implementing cron-driven, replay-safe recurring job scheduling on top of `croner`.                                                                                                                                                                     |
+| [lib/Pubsub.js](./lib/Pubsub.js)         | `definePubsub` (register a pubsub Virtual Object on your endpoint), `pubsubPublisher` (publish into it from inside a handler, in-process), `pubsubClient` (publish/pull/subscribe to it from anywhere else, over the network) — thin wrappers around `@restatedev/pubsub`/`@restatedev/pubsub-client`. |
+| [lib/Validation.js](./lib/Validation.js) | `withValidation` — wraps a workflow handler with input/output JSON schema validation via `@empyria/common`.                                                                                                                                                                                            |
 
 There is no official Restate Admin API client (verified directly against the published
 `@restatedev/restate-sdk`/`-clients` packages) — `lib/Admin.js` is a hand-written wrapper kept

package/index.js

@@ -5,3 +5,5 @@ export * from './lib/Cron.js'
 export * from './lib/Admin.js'
 
 export * from './lib/Caller.js'
+
+export * from './lib/Pubsub.js'

package/lib/Admin.js

@@ -6,7 +6,6 @@ import { setTimeout as sleep } from 'timers/promises'
 
 import * as restate from '@restatedev/restate-sdk'
 import * as clients from '@restatedev/restate-sdk-clients'
-import { createPubsubObject } from '@restatedev/pubsub'
 
 export { restate, clients }
 
@@ -438,21 +437,6 @@ export function defineObject(def) {
 	return restate.object(def)
 }
 
-/**
- * Typed wrapper around `@restatedev/pubsub`'s `createPubsubObject`; see {@link defineWorkflow}.
- * Unlike `defineWorkflow`/`defineService`/`defineObject`, there's no handler map to write —
- * `createPubsubObject` returns a complete `VirtualObjectDefinition` on its own (pull/publish/
- * subscribe/truncate), so this exists purely for the same "one `define*` per Restate construct"
- * naming consistency, not to add behavior. Register the result alongside your other
- * services/objects on the same endpoint (see `setupRestate`'s `services` param) — that's what
- * makes the endpoint's ingress serve `/pubsub/<topic>` as an SSE stream for it.
- * @param {Parameters<typeof createPubsubObject>[0]} name
- * @param {Parameters<typeof createPubsubObject>[1]} [options]
- */
-export function definePubsub(name, options) {
-	return createPubsubObject(name, options)
-}
-
 /**
  * Starts the HTTP/2 Restate endpoint, a health-check HTTP server, registers
  * the deployment with the admin API, and wires SIGTERM/SIGINT for graceful

package/lib/Pubsub.js

@@ -0,0 +1,51 @@
+import { createPubsubObject, createPubsubPublisher } from '@restatedev/pubsub'
+import { createPubsubClient } from '@restatedev/pubsub-client'
+
+/**
+ * Typed wrapper around `@restatedev/pubsub`'s `createPubsubObject`; see `Admin.js`'s
+ * `defineWorkflow`/`defineService`/`defineObject` for the same "typed wrapper, plain passthrough
+ * in JS" pattern this follows. Unlike those three, there's no handler map to write —
+ * `createPubsubObject` returns a complete `VirtualObjectDefinition` on its own (pull/publish/
+ * subscribe/truncate), so this exists purely for the same "one `define*` per Restate construct"
+ * naming consistency, not to add behavior.
+ *
+ * Register the result alongside your other services/objects on the same endpoint (see
+ * `setupRestate`'s `services` param — Admin.js) — that registration is what lets Restate route to
+ * it at all. Restate's own ingress does NOT serve a ready-made SSE route for it, though: reaching
+ * it from a browser needs an app-owned relay built on {@link pubsubClient}'s own `.sse()` (or a
+ * hand-rolled loop over `.pull()`, e.g. to log each message before forwarding it) — confirmed
+ * directly against `@restatedev/pubsub-client`'s compiled source, 2026-08-24, after an earlier,
+ * wrong assumption that this was automatic.
+ * @param {Parameters<typeof createPubsubObject>[0]} name
+ * @param {Parameters<typeof createPubsubObject>[1]} [options]
+ */
+export function definePubsub(name, options) {
+	return createPubsubObject(name, options)
+}
+
+/**
+ * Typed wrapper around `@restatedev/pubsub`'s `createPubsubPublisher` — the in-process publish
+ * path. Call the returned function from inside any handler that already has `ctx` and shares a
+ * Restate endpoint with the pubsub object it targets (both registered via the same `services`
+ * list passed to `setupRestate` — see {@link definePubsub}). Under the hood it's
+ * `ctx.objectSendClient({name}, topic).publish(message)` — a real Restate call, already covered
+ * by the invocation's own journal, so callers don't need to wrap it in an extra `ctx.run()`
+ * themselves (unlike a plain `fetch()`-based call, e.g. `sendMessageAsync` in Admin.js, which
+ * does).
+ * @param {Parameters<typeof createPubsubPublisher>[0]} name
+ */
+export function pubsubPublisher(name) {
+	return createPubsubPublisher(name)
+}
+
+/**
+ * Typed wrapper around `@restatedev/pubsub-client`'s `createPubsubClient` — the out-of-process
+ * counterpart to {@link pubsubPublisher}/{@link definePubsub}: a network client (`pull`/`sse`/
+ * `publish`/`truncate`) for anything that ISN'T a handler on the same Restate endpoint as the
+ * pubsub object — a separate process relaying to a browser, an external consumer, ... — reaching
+ * it over a plain ingress URL instead of `ctx.objectSendClient`.
+ * @param {Parameters<typeof createPubsubClient>[0]} pubsubOptions
+ */
+export function pubsubClient(pubsubOptions) {
+	return createPubsubClient(pubsubOptions)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
@@ -27,6 +27,7 @@
 		"@empyria/classification": "0.1.2",
 		"@empyria/common": "0.1.2",
 		"@restatedev/pubsub": "0.3.2",
+		"@restatedev/pubsub-client": "0.3.2",
 		"@restatedev/restate-sdk": "1.16.8",
 		"@restatedev/restate-sdk-clients": "1.16.8",
 		"@restatedev/restate-sdk-core": "1.16.8",

package/test/Admin.test.js

@@ -20,7 +20,6 @@ import {
 	defineWorkflow,
 	defineService,
 	defineObject,
-	definePubsub,
 	createRestateAdmin,
 	restate,
 	clients,
@@ -456,18 +455,6 @@ describe('defineWorkflow / defineService / defineObject', () => {
 	})
 })
 
-describe('definePubsub', () => {
-	test('is a passthrough to createPubsubObject, name and all', () => {
-		const pubsub = definePubsub('pubsub')
-		expect(pubsub.name).toBe('pubsub')
-	})
-
-	test('forwards options (e.g. pullTimeout) to createPubsubObject', () => {
-		const pubsub = definePubsub('pubsub', { pullTimeout: { seconds: 30 } })
-		expect(pubsub.name).toBe('pubsub')
-	})
-})
-
 describe('createRestateAdmin', () => {
 	test('binds restateAdminURL/restateURL across its methods', async () => {
 		globalThis.fetch = mock(async (url) => {

package/test/Pubsub.test.js

@@ -0,0 +1,51 @@
+import { describe, test, expect } from 'bun:test'
+import { definePubsub, pubsubPublisher, pubsubClient } from '../lib/Pubsub.js'
+
+describe('definePubsub', () => {
+	test('is a passthrough to createPubsubObject, name and all', () => {
+		const pubsub = definePubsub('pubsub')
+		expect(pubsub.name).toBe('pubsub')
+	})
+
+	test('forwards options (e.g. pullTimeout) to createPubsubObject', () => {
+		const pubsub = definePubsub('pubsub', { pullTimeout: { seconds: 30 } })
+		expect(pubsub.name).toBe('pubsub')
+	})
+})
+
+describe('pubsubPublisher', () => {
+	test('returns a function that publishes via ctx.objectSendClient', () => {
+		let capturedTarget
+		let capturedKey
+		let capturedMessage
+		const fakeCtx = {
+			objectSendClient: (target, key) => {
+				capturedTarget = target
+				capturedKey = key
+				return {
+					publish: (message) => {
+						capturedMessage = message
+					},
+				}
+			},
+		}
+
+		const publish = pubsubPublisher('pubsub')
+		publish(fakeCtx, 'agent-service', { event: 'ask-triggered' })
+
+		expect(capturedTarget).toEqual({ name: 'pubsub' })
+		expect(capturedKey).toBe('agent-service')
+		expect(capturedMessage).toEqual({ event: 'ask-triggered' })
+	})
+})
+
+describe('pubsubClient', () => {
+	test('is a passthrough to createPubsubClient exposing pull/sse/publish/truncate', () => {
+		const client = pubsubClient({ url: 'http://localhost:8080', name: 'pubsub' })
+
+		expect(typeof client.pull).toBe('function')
+		expect(typeof client.sse).toBe('function')
+		expect(typeof client.publish).toBe('function')
+		expect(typeof client.truncate).toBe('function')
+	})
+})