@empyria/restate 0.1.0

package/.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "./node_modules/oxfmt/configuration_schema.json",
+	"ignorePatterns": [],
+	"useTabs": true,
+	"tabWidth": 4,
+	"singleQuote": true,
+	"trailingComma": "all",
+	"semi": false
+}

package/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Restate.dev helpers for **Principia**, a nanoservice framework built primarily on Bun:
+an Admin API client, a dynamic-dispatch service, cron-driven workflow scheduling, and
+schema validation for workflow handlers.
+
+Targets Restate server `1.7.x` and `@restatedev/restate-sdk` `1.6.x` — check both when
+touching version pins; the SDK's own version numbering runs well ahead of the server's
+(e.g. `1.16.x` was latest on npm when `1.6.x` was what this repo targets), so "latest"
+is not the right default here.
+
+## Runtime
+
+- Requires Bun `>=1.4.0` or Node.js `>=26`, inherited from `@empyria/classification`'s use
+  of native `Temporal`. Both `@empyria/classification` and `@empyria/common` are **git
+  dependencies** — this package only sees their pushed commits, not local working-tree changes
+  in sibling repos.
+- Plain ESM, no TypeScript, no build step. The original `admin.ts`/`admin.types.ts`/`Caller.ts`
+  (and the `generateTypes.sh` script that regenerated `admin.types.ts` from a live server's
+  `/openapi` spec) have been removed — `lib/Admin.js`/`lib/Caller.js` are the canonical,
+  hand-converted, tested equivalents. There is no generated-types workflow left in this repo;
+  if the Admin API needs re-syncing, diff `lib/Admin.js`'s assumptions against a live server's
+  `<admin-url>/openapi` by hand.
+- Relative imports must include explicit `.js` extensions — Bun tolerates missing ones, Node's
+  ESM resolver doesn't.
+
+## No official Admin API client
+
+Verified directly against the published `@restatedev/restate-sdk`/`-clients` package
+internals (both the `1.6.x` line this repo targets and the latest available at the time):
+zero Admin API exports. Only the ingress/invocation client and the service-authoring API
+(`restate.service`/`object`/`workflow`) are official. `lib/Admin.js` fetches the Admin API's
+REST endpoints directly — that's not a stopgap, it's the only way to do this today.
+
+## Testing Restate service/object definitions
+
+`restate.service({...})`/`restate.object({...})` do **not** return your handler functions
+under `.handlers` — that property doesn't exist on the returned definition. The raw handler
+functions are reachable at `.service` (for `restate.service`) or `.object` (for
+`restate.object`), e.g. `cronJob.object.initiate(mockCtx, request)`. See `test/Cron.test.js`.
+
+`@restatedev/restate-sdk-clients`'s `clients` export (re-exported from `lib/Admin.js`) is a
+live ESM namespace binding — you cannot reassign `clients.connect` directly (`TypeError:
+Attempted to assign to readonly property`). Use `mock.module('@restatedev/restate-sdk-clients',
+() => ({...}))` instead, and capture the _real_ `connect` function once at module load (before
+any mocking) if you need to restore it — reading it back off the live `clients` binding later
+may observe an already-mocked value. See `test/Admin.test.js`.
+
+`setupRestate` (in `lib/Admin.js`) is not unit tested: it binds real HTTP/2 + health-check
+ports, installs process-wide `SIGTERM`/`SIGINT` handlers, and its returned `forceClose` calls
+`process.exit()` — none of which are safe to exercise in-process in a test run.
+
+## Zero-dependency preference
+
+Cron parsing uses `croner` (zero dependencies), not `cron-parser` (pulls in `luxon`). If you
+touch `lib/Cron.js`'s scheduling logic: `new Cron(pattern)` without a callback just parses —
+it does not start a timer — and `.nextRun(referenceDate)` is what gives a deterministic next
+run time from Restate's replay-safe `ctx.date.now()`, matching the library's actual API rather
+than `cron-parser`'s `CronExpressionParser.parse(...).next()` shape.
+
+## Style
+
+- Formatting is enforced by oxfmt ([.oxfmtrc.json](./.oxfmtrc.json)): tabs, single quotes, no
+  semicolons, trailing commas. Run `bun run format:fix` before committing.

package/README.md

@@ -0,0 +1,78 @@
+# @empyria/restate
+
+[Restate.dev](https://restate.dev) helpers for **Principia**, a nanoservice framework built
+primarily on Bun: an Admin API client, a generic dynamic-dispatch service, cron-driven
+workflow scheduling, and Restate-aware input/output schema validation.
+
+Targets Restate server `1.7.x` and `@restatedev/restate-sdk` `1.6.x`.
+
+## Requirements
+
+- Bun `>=1.4.0` or Node.js `>=26`
+- Plain ESM, no build step, no TypeScript
+
+Both requirements come from [@empyria/classification](https://github.com/imrefazekas/empyria-classification)
+and [@empyria/common](https://github.com/imrefazekas/empyria-common), which this package
+depends on and which use the native `Temporal` global for all date/time handling.
+
+## Install
+
+```bash
+bun add @empyria/restate
+```
+
+## Usage
+
+```js
+import { createRestateAdmin, withValidation, cronJob, cronJobInitiator } from '@empyria/restate'
+
+const admin = createRestateAdmin({
+	restateAdminURL: 'http://localhost:9070',
+	restateURL: 'http://localhost:9071',
+})
+
+const services = await admin.listServices()
+```
+
+Everything is re-exported from the package root via [index.js](./index.js). Individual
+modules under `lib/` can also be imported directly if you only need one:
+
+```js
+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, 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`.                                                                                                   |
+
+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
+in sync with the live Admin API's OpenAPI spec (`<admin-url>/openapi`) by hand.
+
+Every exported function is documented with JSDoc directly in its source file — hovering
+a function in VSCode or Zed shows its parameters and return type without any extra
+tooling, since both editors read JSDoc from plain `.js` files automatically.
+
+Tests live under [test/](./test/), one file per module, separate from the sources. They
+mock `fetch` and the Restate SDK client rather than requiring a live server — the one
+exception is `setupRestate`, which binds real ports and installs process signal handlers
+and is deliberately left untested (see [AGENTS.md](./AGENTS.md)).
+
+## Scripts
+
+```bash
+bun run format       # check formatting (oxfmt)
+bun run format:fix   # apply formatting
+bun run lint         # lint (oxlint)
+bun run lint:fix     # lint and fix
+bun run test         # run tests with coverage
+```
+
+## License
+
+MIT © Imre Fazekas

package/index.js

@@ -0,0 +1,7 @@
+export * from './lib/Validation.js'
+
+export * from './lib/Cron.js'
+
+export * from './lib/Admin.js'
+
+export * from './lib/Caller.js'