@openknot-ts/behavior
v0.0.6-preview
Published
Functional models, operations and reader contracts with typed outcomes.
Readme
@openknot-ts/behavior
Pure business logic: models, operations, reader contracts and functional errors. No container, reflection, decorators or code generation. @openknot-ts/wire is a required peer whose small helpers the root entry shares without loading the container; /wire adds DI provision.
pnpm build
pnpm --filter @openknot-ts/behavior test
pnpm --filter @openknot-ts/behavior example # examples/roles.ts, standalone
pnpm --filter @openknot-ts/behavior example:wire # examples/wired-roles.ts, with DIModels
A model owns state and its rules. With a Standard Schema, the state is inferred from it:
import { model, success } from "@openknot-ts/behavior";
import { z } from "zod";
const roleNameSchema = z.string().trim().min(1);
const roleSchema = z
.object({
id: z.string().min(1),
name: roleNameSchema,
})
.readonly();
type RoleState = z.infer<typeof roleSchema>;
export const Role = model({
name: "role",
invariants: roleSchema,
mutations: {
rename: (role: RoleState, name: string) => success({ ...role, name }),
},
queries: {
isNameValid: (name: string) => roleNameSchema.safeParse(name).success,
displayName: (role: RoleState) => role.name,
},
});Without a schema, declare the state on the head: model<State>()({ mutations, queries?, invariants? }).
- Mutations return
Outcome<State, E>. Every successful result is validated through the schema's~standard.validate(); the parsed value (normalized, transformed) becomes the state. Failures returnModelValidationErrorwith standardissues. Declared mutation failures skip validation. - Behavior depends only on the
StandardSchemaV1type from@standard-schema/spec; the schema library is the application's. invariantsis a schema or a synchronous(state) => Outcome<void, E>whose errors join every mutation's result.- Queries are synchronous pure functions with their own arguments and return types; they do not run invariants.
- Mutations and queries are called directly on the model,
Role.rename(role, name), share one namespace and must be synchronous.nameis an optional diagnostic label. - Models are plain public exports: no registration. The schema stays an ordinary export that fixture loaders and boundaries reuse.
Operations
An operation computes a business change: it reads through reader contracts, applies rules that need dependencies (such as uniqueness), calls model mutations and declares events.
import type { Event } from "@openknot-ts/behavior";
import { operation, success, unchanged, updated } from "@openknot-ts/behavior";
type RoleEvent = Event &
(
| { readonly type: "RoleCreated"; readonly roleId: string }
| { readonly type: "RoleRenamed"; readonly roleId: string }
);
const renameRole = operation<{ readonly role: RoleState; readonly name: string }, RoleState, RoleEvent>()({
run: ({ role, name }) => {
const renamed = Role.rename(role, name);
if (renamed.isError) {
return renamed;
}
if (renamed.value.name === role.name) {
return success({ output: unchanged(role), events: [] });
}
return success({
output: updated(renamed.value),
events: [{ type: "RoleRenamed" as const, roleId: role.id }],
});
},
});operation<Input, State, Event>()({ requirements?, run, tag? }): types go on the head, so the definition reads like a signature; requirements and errors are inferred. State and Event are optional. With nothing to declare, operation({ ... }) takes no input.
Outputs
Every success carries a fixed output, built with a helper:
| Helper | Type | Descriptor |
| --- | --- | --- |
| created(state) | Created<State> | { changeType: "created", next: state } |
| updated(state) | Updated<State> | { changeType: "updated", next: state } |
| deleted(state) | Deleted<State> | { changeType: "deleted", previous: state } |
| unchanged(state) | Unchanged<State> | { changeType: "unchanged", current: state } |
OperationOutput<State> is their union; name one when run declares its output, for example Created<Role> | Unchanged<Role>. Deleted<Payload> also types persistence writers. Helpers freeze their own wrapper and keep the state by reference.
One decision that changes several states of the same model returns a list, each change with its own type, for example output: [updated(kept), deleted(merged)]. An empty list means nothing changed.
Events
- With an
Eventtype,runreturnsevents: readonly Event[]([]when none). Without one, results have noeventsproperty and authoring rejects them. unchangedresults, and lists of onlyunchangedresults or no results, must carry an empty event array.Eventis a types-only{ readonly type: string }. Name each model's union<ModelName>Event, such asRoleEvent, with a variant pertype, for exampleinterface RoleRenamed extends Event<"RoleRenamed"> { readonly role: RoleState }.- Child operations in
ctxreturn their own results; their events are never merged automatically.
The operation decides no-ops: the framework never compares states. Flow persists and publishes; an operation performs no infrastructure effects besides logging through logger from @openknot-ts/logging/wire, which never changes its outcome.
Derived types
import type { OperationErrors, OperationEvents, OperationInput } from "@openknot-ts/behavior";
type RenameRequest = OperationInput<typeof renameRole>;
type AllowedEvents = OperationEvents<typeof renameRole>; // RoleEvent, or never without an event type
type RenameErrors = OperationErrors<typeof renameRole>; // the authored errorsA Flow command can declare its input as command<OperationInput<typeof renameRole>>().
Errors
export const AccessDenied = error("AccessDenied");
export const RoleNotFound = error("RoleNotFound", (id: string) => ({ message: `Role ${id} was not found`, id }));
failure(RoleNotFound("r1"));- Each call creates a frozen
Errorwith a literaltype, message, optional cause and the caller's stack. A describer cannot returnname,stackortype. - Check with
switch (error.type)orRoleNotFound.is(value), neverinstanceof. - Name the type only where needed:
type RoleNotFound = ReturnType<typeof RoleNotFound>. Packages that publish declarations useinterface RoleNotFound extends ReturnType<typeof RoleNotFound> {}. - Return expected failures with
failure(error). Anything thrown, or rejected, inside an operation, reader call, mutation or invariant is thrown asInternalBehaviorErrorwith the originalcause; it never joins an inferred error union. - Detached promises and timers are outside the boundary.
Readers
reader<F>() declares a contract; the resolved reader is the bound function. Identity is the reference, not the name or signature. reader.compose({ findRole, listRoles }) groups readers for one plug; each stays independently injectable. A managed entity is a state with an entity literal (the model name) and a scalar id; Flow's managed writers track it, plain states are never tracked.
Infrastructure implements readers with plug() from @openknot-ts/wire (typed by @openknot-ts/behavior/wire):
plug({ port: reader.compose({ findRole, listRoles }), requirements: { database }, bind: ({ database }) => ({ findRole, listRoles }) });Caching stays outside Behavior: @openknot-ts/cache and @openknot-ts/replication decorate readers.
Running without an application
standalone(operation, overrides?) runs an operation with explicitly supplied readers, for scripts and tests. Missing or duplicate readers and cycles fail before execution. A required logger writes on the console unless override(logger, value) supplies one.
import { operation, reader, standalone, success, updated } from "@openknot-ts/behavior";
import { override } from "@openknot-ts/wire";
const currentCount = reader<(id: string) => Promise<number>>();
const incrementCounter = operation<string>()({
requirements: { currentCount },
run: async (id, ctx) => success({ output: updated((await ctx.currentCount(id)) + 1) }),
});
const runIncrement = standalone(incrementCounter, [override(currentCount, () => Promise.resolve(3))]);
const result = await runIncrement("counter-1");Resolved operations always return a Promise of an Outcome.
Provision with Wire
A package index publishes its operations with provideBehavior() from @openknot-ts/behavior/wire:
import { provideBehavior } from "@openknot-ts/behavior/wire";
import { roleOperations } from "./operations/roles.ts";
// Leave the type inferred: it carries the graph the compile-time check reads.
export const behavior = provideBehavior([roleOperations]);- Sources are operations,
operation.compose({ renameRole, deactivateRole })groups, native Wireunit()s, namespaces and import loaders with literal specifiers, such as() => import("./role.operations.ts"). Models, readers, resources and plugs are rejected. - Readers and private child operations join through
requirements; operations may require only readers, operations andlogger. - Operations need no module of their own in an application: its
inputsreach them through requirements. A provided module can still be listed indefineApplication({ modules }), whereincludeOnly,exclude,whenandrequiredByselect from it. - Operations and readers are scoped: resolve them inside
app.withScope(work, { root: operation }), which acquires only what that operation can reach. Missing implementations fail atrunApplication().
const behavior = provideBehavior([increment]);
const storage = composeModule({
providers: {
countBinding: plug({ port: currentCount, bind: () => () => Promise.resolve(3) }),
},
});
const app = await runApplication(defineApplication({ modules: storage.requiredBy(behavior) }));
try {
console.log(await app.withScope((scope) => scope.resolve(increment)(), { root: increment }));
} finally {
await app.stop();
}test/composition-types.ts checks allowed sources and inferred signatures. The quick-start and modular examples use this package in a complete application.
