npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@agentback/actors-do

v0.13.0

Published

Durable Objects ActorRuntime adapter — one object per identity, storage-backed state/dedup/journal, targeting Cloudflare DO and celld

Readme

@agentback/actors-do

Durable Objects adapter for the @agentback/actors runtime port — one object per actor identity, with state, the idempotency (dedup) record, and the per-identity event journal persisted in the object's own storage and committed in a single atomic multi-key put.

The adapter targets the portable Durable Objects surface: the intersection of Cloudflare Durable Objects and celld (the self-hosted DO runtime) — idFromName addressing, RPC stubs, and SQLite-backed storage with atomic multi-key writes. Nothing Cloudflare-only (Queues, KV, alarms) is required.

What the platform gives, what the engine adds

A Durable Object is a single instance per name, globally — that is the mutual-exclusion placement guarantee the Redis adapter builds with leases and Lua scripts. It is not per-turn serialization: workerd interleaves in-flight requests at await points, so the object runs its own seat (a promise-chain mutex), and the rest of the actor contract — Zod validation, rollback, requestId dedup and collision rejection, per-seat-class deadlines, the timeout marker, the journal — is the same engine contract as every other adapter, verified by the shared runActorRuntimeConformance suite.

One structural difference an async store forces: the deadline races load + receive only, and the commit runs outside the race, serialized through a single storage section. An abandoned turn (deadline fired mid-phase) never reaches its commit — the race discards the continuation — so the only abandoned write left is initialState persistence, which re-checks first-writer-wins inside the section. Same caller-visible semantics as Redis ("a stalled commit makes one caller wait"), same recorded-failed-turn markers as the in-process journaling runtime.

In-process (tests, dev, single process)

import {ACTOR_REGISTRY} from '@agentback/actors';
import {
  createInProcessDoActorRuntime,
  installDurableObjectActors,
} from '@agentback/actors-do';

const app = new Application();
installDurableObjectActors(app, {runtime: createInProcessDoActorRuntime()});
app.service(CartActor); // the same @actor class, unchanged
await app.start();

const actors = await app.get(ACTOR_REGISTRY);
await actors.ref(CartActor, 'ada').add({sku: 'kbd'}, {requestId: 'r1'});

createInProcessDoActorRuntime() wires the real engine to an in-memory host that mimics the platform where it matters: calls cross the stub as structured clones, and are delivered concurrently (never queued), so the engine's own serialization is what's exercised.

Cloudflare / celld deployment shape

Both sides of the RPC boundary must be able to construct the same ActorDefinitions from the shared module graph — a Durable Object may run in a different isolate (or machine) than the Worker that calls it, so the definitions cannot be captured from the caller's live runtime.

// actor-definitions.ts — shared by the Worker and the DO class
export function actorDefinitions() {
  return [cartDefinition /* , ... */];
}

// worker.ts — the module Cloudflare/celld loads
import {DurableObject} from 'cloudflare:workers';
import {
  createActorDurableObject,
  DurableObjectActorRuntime,
} from '@agentback/actors-do';
import {actorDefinitions} from './actor-definitions.js';

// baseClass matters on Cloudflare: RPC methods are exposed only from
// classes extending DurableObject, and that module exists only inside
// workerd — which is why the factory takes it as a parameter.
export const ActorDO = createActorDurableObject(actorDefinitions, {
  baseClass: DurableObject,
});

export default {
  async fetch(request: Request, env: Env) {
    const runtime = new DurableObjectActorRuntime(env.ACTORS);
    for (const definition of actorDefinitions()) runtime.register(definition);
    // hand `runtime` to installDurableObjectActors / your EdgeRestApplication
  },
};
// wrangler.jsonc — celld accepts jsonc (not toml) and rejects unknown keys
{
  "name": "my-service",
  "main": "dist/worker.js",
  "compatibility_date": "2026-08-01",
  "compatibility_flags": ["js_rpc"],
  "durable_objects": {
    "bindings": [{"name": "ACTORS", "class_name": "ActorDO"}],
  },
  "migrations": [{"tag": "v1", "new_sqlite_classes": ["ActorDO"]}],
}

Storage layout

Per object (one identity): record holds {actor, state, seq} and stays deliberately small; each committed request result lives in its own dedup:<requestId> key (O(1) replay lookup), with a dedup-order index for FIFO eviction (dedupLimit, default 1024 — a replay of an evicted requestId re-runs); events append as event:<seq> keys. The commit is one atomic multi-key put of all of it; evicted dedup keys are deleted lazily after (an orphan only makes a replay more correct). Two platform constraints shape this: a single storage entry is capped (128 KiB on KV-backed classes, 2 MB key+value on SQLite-backed), which is why dedup results are never accumulated into one value, and one put carries a bounded number of entries, which is why a turn may emit at most 100 events (enforced on every host, so dev fails the same way production would).

Journal: read half only

The adapter persists a turn's events atomically with its commit and appends the reserved actor.turn.timeout marker for a timed-out turn whose identity record exists (a cold identity that times out mid-initialState gets the log line only, matching the in-process journaling runtime; the marker write is best-effort and never masks the caller's TurnTimeoutError), so registry.events(type, id) works exactly as on the journaling runtimes. It implements ActorEventReader, not ActorEventStore: a Durable Object has no portable push channel back to every caller, so registry.subscribe(...) throws with the runtimes that do deliver named. Read the log by identity, or bind EventSourcedActorsComponent / RedisActorsComponent when you need live delivery.

Exports

  • createActorDurableObject(loadDefinitions, {dedupLimit?}) — the DO class factory (export the result from your worker module).
  • DurableObjectActorRuntime — caller-side ActorRuntime + ActorEventReader over a namespace binding.
  • installDurableObjectActors(app, {namespace | runtime}) — binds ACTOR_RUNTIME + ActorRegistry.
  • InProcessDurableObjectHost, createInProcessDoActorRuntime — the single-process host.
  • ActorDoStorage / ActorDoState / ActorDoNamespace / ActorDoStub — the structural platform surface (no Cloudflare type dependency).
  • TurnRequest / TurnOutcome / serializeActorError / reviveActorError — the RPC envelope; errors cross the boundary as data and are revived typed (TurnTimeoutError keeps naming the turn whose deadline fired, domain-error code/status/hint properties survive).

Layering

@agentback/actors defines the port and the authoring model; this package is an adapter beside InMemoryActorsComponent (tests), the event-sourced in-memory runtime, and @agentback/actors-redis (container fleets sharing a Redis). Reach for it when the app deploys to Cloudflare Workers (EdgeRestApplication + agentback deploy cloudflare) or a self-hosted celld cluster.