@netscript/plugin-sagas

NetScript plugin for durable saga orchestration, workflow APIs, and saga runtime metadata. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The published plugin exposes the host-facing plugin manifest, the executable saga runtime and supervisor, the HTTP publisher, the versioned API contract, and the browser-safe stream surface. The userland saga DSL (defineSaga, the cascaded-message constructors) is authored against @netscript/plugin-sagas-core and re-exported through the runtime entrypoint. That separately published package has its own canonical reference page.

Entrypoints

The plugin publishes the following entrypoints. Each is documented against its own deno doc surface.

Plugin manifest (@netscript/plugin-sagas)

The root entrypoint exposes the plugin manifest and stable identifiers. Shared manifest inspection is provided by inspectPlugin from @netscript/plugin.

Runtime (@netscript/plugin-sagas/runtime)

The runtime entrypoint provides the executable saga runtime and the building blocks a composition root wires together. It also re-exports the userland DSL types and cascaded-message vocabulary from @netscript/plugin-sagas-core.

Runtime entry functions and classes

Runtime ports and facade

Durability and lifecycle vocabulary

The runtime entrypoint exports 95 symbols in total. The tables above list the primary surface. Branded id aliases (SagaId, SagaInstanceId, SagaMessageId, SagaCorrelationKey), scheduler records and publisher receipt/JSON types are part of the published surface and resolve through deno doc plugins/sagas/src/runtime/mod.ts.

API contract (@netscript/plugin-sagas/contracts)

Version 1 of the sagas plugin API contract, its Zod schemas, and the router types.

Streams (@netscript/plugin-sagas/streams)

Browser-safe stream exports for the sagas plugin.

CLI, scaffolding, and Aspire

Core package

The separately published @netscript/plugin-sagas-core page is canonical for the saga DSL, runtime ports, adapters, telemetry, configuration, and testing exports. This page stays focused on the deployable plugin's manifest and integration entrypoints. The testing example below uses the core package intentionally; exhaustive core entrypoint and symbol tables live only on its reference page.

The unsupported spawn(child, input, options?: SpawnOptions): never contract is worth calling out: it throws immediately rather than starting a child saga. Its full description and every other core symbol live on the canonical core page.

Deterministic Testing

Durable sagas can be tested without external message buses or databases using createTestSagaRuntime from @netscript/plugin-sagas-core/testing. This provides an in-memory bus, store, and controllable clock to assert on emitted side-effects.

import { assertEquals } from "@std/assert";
import { defineSaga, send, type SagaState } from "@netscript/plugin-sagas-core";
import { createTestSagaRuntime } from "@netscript/plugin-sagas-core/testing";

Deno.test("Saga testing with createTestSagaRuntime and controllable clock", async () => {
  const runtime = createTestSagaRuntime();

  // Define a simple saga using the recommended SagaState type for registration compatibility
  const checkoutSaga = defineSaga("CheckoutSaga")
    .state<SagaState>({ orderId: "", total: 0, status: "pending" })
    .on<string, unknown>("OrderCreated", (saga, event) => {
      const payload = event.payload as { orderId: string; total: number };
      saga.state = {
        ...saga.state,
        orderId: payload.orderId,
        total: payload.total,
        status: "processing",
      };
      return [send("PaymentRequested", { orderId: payload.orderId, total: payload.total })];
    })
    .build();

  // Start the test runtime
  await runtime.start();
  await runtime.register([checkoutSaga]);

  // Publish a starting event
  const event = {
    type: "OrderCreated",
    payload: { orderId: "ord_123", total: 500 },
  };
  await runtime.publish(event);

  // Assert that the message was recorded on the test bus
  const published = runtime.bus.published();
  assertEquals(published.length, 1);
  assertEquals(published[0].message.type, "OrderCreated");
  assertEquals(published[0].message.payload, { orderId: "ord_123", total: 500 });

  // Controllable clock assertion
  // The test saga clock starts at a default time, and sleep advances it.
  assertEquals(runtime.clock.now().toISOString(), "2026-01-01T00:00:00.000Z");
  
  await runtime.clock.sleep(500);
  assertEquals(runtime.clock.now().toISOString(), "2026-01-01T00:00:00.500Z");
  assertEquals(runtime.clock.sleeps(), [500]);

  // Stop the runtime
  await runtime.stop();
});

Back to the reference overview.