Skip to content

Lint rules

@akterjs/oxlint-plugin is the akter plugin for Oxlint. Its rules keep app code in the actor grammar and catch what the type checker misses or reports with an unclear message. Every message names the problem, gives the reason, and ends with the canonical fix, so you or a coding agent can fix the code from the message alone.

  1. Install the plugin and Oxlint as dev dependencies.
Terminal
bun add -d @akterjs/oxlint-plugin oxlint
  1. Extend the recommended config in oxlint.config.ts.
oxlint.config.ts
import { recommended } from "@akterjs/oxlint-plugin/recommended"
import { defineConfig } from "oxlint"

export default defineConfig({ extends: [recommended] })
  1. To use a JSON config instead, extend recommended.json in .oxlintrc.json.
.oxlintrc.json
{ "extends": ["./node_modules/@akterjs/oxlint-plugin/recommended.json"] }
  1. Run Oxlint on your source folders.
Terminal
bunx oxlint src tests

The recommended config turns on every rule below at error.

Where each rule looks⁠

RuleCode it checksAutofix
akter/actor-determinismActor handlersNo
akter/actor-no-networkActor handlersNo
akter/canonical-search-indexEvery fileNo
akter/declarative-bindingsEvery fileNo
akter/explicit-schemasEvery fileYes
akter/job-state-through-turnJob layers, outside <Actor>.turn runsNo
akter/no-raw-sqlActor handlers, job layers, and <Actor>.turn runsNo
akter/required-slotsEvery fileNo
akter/state-machine-statusSchema.TaggedStruct in every file, and Schema.Struct in the states slot of Akter.makeNo
akter/symbol-referencesEvery fileYes
akter/turn-no-io<Actor>.turn runs and actor handlersNo

The rules find each scope by its syntax and never read the file name. One plain .ts file can hold an actor’s contract, tables, handlers, and jobs.

  • Actor handlers: The object in Sale.toLayer({ commands, initial, queries }), including results and upgrade. An object counts as an actor layer when it holds commands, initial, and queries. An object with a spread counts when it holds one of the three.
  • Job layers: The function in Sale.jobs.restock.toLayer(...).
  • Turn runs: The run handler in Sale.turn({ from, to, run }).

A scoped rule also follows the names that a scope uses. When a scope uses a name that the same file declares at the top level, the rule checks every function in that declaration. The rule follows such names from one top-level declaration to the next, so Sale.toLayer(saleHandlers) and a shared Effect.fn helper get the same checks. A scope that uses one member of a top-level object reaches every function in that object. A scope that uses a top-level value also reaches the helper that built the value, such as signalOf in const Approval = signalOf("approval").

A scoped rule does not check these cases:

  • Module-load code: Code in a top-level declaration that runs when the module loads, such as the http slot of Akter.make. A helper that only an Akter declaration calls is also unchecked.
  • Imported helpers: A helper that the file imports, because a rule reads one file at a time.
  • Other declarations: A helper that a destructuring declaration or a namespace block declares.

The rules read Akter only when a file imports it from @akterjs/effect or one of its subpaths. To apply the autofixes, run bunx oxlint --fix src.

akter/actor-determinism⁠

  • Rejects: Date.now(), new Date() with no argument, Date(), performance.now(), Math.random(), crypto.randomUUID(), crypto.getRandomValues(), setTimeout, setInterval, and setImmediate in an actor handler.
  • Why: A command replays from its journal, so every value it reads must come from the engine. A timer outside the journal is lost on restart.
  • Fix: Read the time with yield* Akter.now, mint ids with yield* Akter.id, and draw numbers from Effect’s Random module. Queue a timer with Akter.timer(delay, Invite.commands.expire, input).

akter/actor-no-network⁠

  • Rejects: A value from a network module, such as effect/http, node:https, undici, or ws, in an actor handler. It also rejects a dynamic import() of a network module and the global fetch, WebSocket, XMLHttpRequest, and EventSource there.
  • Why: A command handler is a deterministic turn. Network I/O inside a turn breaks replay and exactly-once retries.
  • Fix: Move the external call into a job layer, such as Sale.jobs.restock.toLayer(...). Start the job with Akter.start, and land its result in the actor’s results handler.
  • Option: modules replaces the list of banned modules, such as ["error", { "modules": ["effect/http", "undici"] }].

akter/canonical-search-index⁠

  • Rejects: An Akter.searchIndex call that is not a property value of the object that searchIndexes returns in Akter.table options. It also rejects a searchIndexes value that is not written (columns) => ({ ... }). An index key fails when it is computed, does not match ^[a-z][a-z0-9_]*$, or is longer than 32 characters. An Akter.search call fails when its index argument is not a string literal.
  • Why: A search index belongs to one table, and akterd builds it from that table’s declaration. Index names are snake_case, and 32 characters is the engine’s index name limit. Akter.search names the index with a literal, so the type checker matches it to a key of searchIndexes.
  • Fix: Write searchIndexes: (columns) => ({ documents_search: Akter.searchIndex({ filters: [columns.tenant], lexical: [columns.title, columns.body], vector: columns.embedding }) }). Search the index with Akter.search(DocumentsTable, "documents_search", { ... }).
  • Scope: A searchIndexes value in another form gets one report, and the Akter.searchIndex calls inside it get none. A key that breaks more than one name rule gets one report.

akter/declarative-bindings⁠

  • Rejects: An inline function, an arrow function, or a call result in the command, query, job, state, cron, or after slot of Akter.timeout, Akter.schedule, Akter.http, Akter.httpQuery, or Akter.httpStream. It also rejects a command, query, or job value that is not a string literal. In Akter.make, it rejects an element of timeouts, schedules, or http that is not a call to the matching constructor.
  • Why: A binding is data that names its target. The manifest, akter verify, and the contract gate read it without running code.
  • Fix: Write the target name as a string, such as command: "archiveIdle". Write the state’s Schema.TaggedStruct value in state. Write each binding as a constructor call inside the list, such as timeouts: [Akter.timeout({ after: Duration.hours(24), command: "archiveIdle", state: Active })].
  • Allowed calls: after takes a Duration call, such as Duration.hours(24). cron takes a Cron call, such as Cron.parseUnsafe("0 * * * *"). Each argument of these calls is a literal or a name.

akter/explicit-schemas⁠

  • Rejects: A plain object in the input or output slot of Akter.command, Akter.query, or Akter.job, and in initial.input of Akter.make. An example is input: { quantity: Quantity }.
  • Why: Every schema slot takes an explicit Schema, so the published contract carries one exact codec.
  • Fix: Write input: Schema.Struct({ quantity: Quantity }). The autofix wraps the object when the file imports Schema from effect.

akter/job-state-through-turn⁠

  • Rejects: Akter.db, Akter.send, Akter.timer, Akter.start, Akter.cancel, Akter.signal, and ActorState in a job layer. Each passes inside the run handler of <Actor>.turn({ from, to, run }), including an Effect.gen or Effect.fn body nested in run.
  • Why: A job changes its actor’s state only inside <Actor>.turn. akterd commits the next state, the SQL writes, and the effects of a run as one step turn.
  • Fix: Move the call into the run handler, and return { next, output } from it.

akter/no-raw-sql⁠

  • Rejects: A sql<T> tagged template, Akter.sql, and a value from effect/sql, effect/unstable/sql, @effect/sql, @effect/sql-*, node:sqlite, bun:sqlite, or better-sqlite3. It also rejects a dynamic import() of those modules. It checks actor handlers, job layers, and <Actor>.turn runs.
  • Why: A sql<T> template casts unchecked rows to T. Handlers reach SQL only through Akter.db, a typed drizzle database over the tables that Akter.table declares.
  • Fix: Declare the table with Akter.table, and list it in the actor’s tables. Query it with yield* Akter.db, such as db.select().from(OrdersTable).where(eq(OrdersTable.id, id)).

akter/required-slots⁠

  • Rejects: An Akter.make call without one of callers, commands, initial, key, parent, queries, states, or tables. It also rejects an empty final, jobs, or secrets slot, and a member without one of its slots.
  • Why: The grammar states every choice, so no default hides one. A facet slot appears only on an actor that uses it.
  • Fix: Add the slot that the message names, such as tables: [], errors: [], or output: Schema.Void. Delete an empty facet slot.
  • Member slots: Akter.command takes callers, errors, from, input, output, and to. Akter.query takes callers, errors, input, output, and states. Akter.job takes errors, from, input, output, patches, and to.

akter/state-machine-status⁠

  • Rejects: A field named status, phase, state, or stage whose schema is a string literal, a union of literals, or an enum. An example is status: Schema.Literals(["open", "paid"]). It checks every Schema.TaggedStruct, and every Schema.Struct in the states slot of Akter.make.
  • Why: A lifecycle inside one struct lets every handler read and write any status. Separate states let Akter.make check each command’s from and to.
  • Fix: Declare one Schema.TaggedStruct per value, such as Open and Paid, and list them in states: [Open, Paid].

akter/symbol-references⁠

  • Rejects: A string in a slot that names a state, caller, error, table, or parent. Examples are states: ["Open"], callers: ["user"], errors: ["SoldOutError"], and initial: { to: "Open" }. A string in secrets or patches passes.
  • Why: A string reference compiles when it is misspelled. A value lets the type checker narrow each handler’s state.
  • Fix: Write the value, such as states: [Open] for const Open = Schema.TaggedStruct("Open", {}). The autofix writes the value when the same file declares exactly one match above the reference.

akter/turn-no-io⁠

  • Rejects: Inside the run handler of <Actor>.turn, every Activity call, such as Activity.make, and HttpClient. It also rejects the global fetch and any use of a network module there. In an actor handler, it rejects a value from effect/workflow and calls to Activity.
  • Why: A turn run and a command or query handler are deterministic turns that akterd commits once. An external call inside them runs again on every replay.
  • Fix: Run the external call as an Activity.make block in the job body before <Actor>.turn, and pass its result into run. Move an Activity in an actor handler into a job layer.
  • Scope: akter/actor-no-network reports network I/O in actor handlers, so this rule reports network I/O only in run handlers. A run handler inside an actor handler counts as a turn run. Each case gets one report.