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.
Turn on the recommended config
- Install the plugin and Oxlint as dev dependencies.
bun add -d @akterjs/oxlint-plugin oxlint- Extend the
recommendedconfig inoxlint.config.ts.
import { recommended } from "@akterjs/oxlint-plugin/recommended"
import { defineConfig } from "oxlint"
export default defineConfig({ extends: [recommended] })- To use a JSON config instead, extend
recommended.jsonin.oxlintrc.json.
{ "extends": ["./node_modules/@akterjs/oxlint-plugin/recommended.json"] }- Run Oxlint on your source folders.
bunx oxlint src testsThe recommended config turns on every rule below at error.
Where each rule looks
| Rule | Code it checks | Autofix |
|---|---|---|
akter/actor-determinism | Actor handlers | No |
akter/actor-no-network | Actor handlers | No |
akter/canonical-search-index | Every file | No |
akter/declarative-bindings | Every file | No |
akter/explicit-schemas | Every file | Yes |
akter/job-state-through-turn | Job layers, outside <Actor>.turn runs | No |
akter/no-raw-sql | Actor handlers, job layers, and <Actor>.turn runs | No |
akter/required-slots | Every file | No |
akter/state-machine-status | Schema.TaggedStruct in every file, and Schema.Struct in the states slot of Akter.make | No |
akter/symbol-references | Every file | Yes |
akter/turn-no-io | <Actor>.turn runs and actor handlers | No |
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 }), includingresultsandupgrade. An object counts as an actor layer when it holdscommands,initial, andqueries. 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
runhandler inSale.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
httpslot ofAkter.make. A helper that only anAkterdeclaration 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
namespaceblock 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, andsetImmediatein 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 withyield* Akter.id, and draw numbers from Effect’sRandommodule. Queue a timer withAkter.timer(delay, Invite.commands.expire, input).
akter/actor-no-network
- Rejects: A value from a network module, such as
effect/http,node:https,undici, orws, in an actor handler. It also rejects a dynamicimport()of a network module and the globalfetch,WebSocket,XMLHttpRequest, andEventSourcethere. - 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 withAkter.start, and land its result in the actor’sresultshandler. - Option:
modulesreplaces the list of banned modules, such as["error", { "modules": ["effect/http", "undici"] }].
akter/canonical-search-index
- Rejects: An
Akter.searchIndexcall that is not a property value of the object thatsearchIndexesreturns inAkter.tableoptions. It also rejects asearchIndexesvalue 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. AnAkter.searchcall fails when its index argument is not a string literal. - Why: A search index belongs to one table, and
akterdbuilds it from that table’s declaration. Index names are snake_case, and 32 characters is the engine’s index name limit.Akter.searchnames the index with a literal, so the type checker matches it to a key ofsearchIndexes. - Fix: Write
searchIndexes: (columns) => ({ documents_search: Akter.searchIndex({ filters: [columns.tenant], lexical: [columns.title, columns.body], vector: columns.embedding }) }). Search the index withAkter.search(DocumentsTable, "documents_search", { ... }). - Scope: A
searchIndexesvalue in another form gets one report, and theAkter.searchIndexcalls 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, orafterslot ofAkter.timeout,Akter.schedule,Akter.http,Akter.httpQuery, orAkter.httpStream. It also rejects acommand,query, orjobvalue that is not a string literal. InAkter.make, it rejects an element oftimeouts,schedules, orhttpthat 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’sSchema.TaggedStructvalue instate. Write each binding as a constructor call inside the list, such astimeouts: [Akter.timeout({ after: Duration.hours(24), command: "archiveIdle", state: Active })]. - Allowed calls:
aftertakes aDurationcall, such asDuration.hours(24).crontakes aCroncall, such asCron.parseUnsafe("0 * * * *"). Each argument of these calls is a literal or a name.
akter/explicit-schemas
- Rejects: A plain object in the
inputoroutputslot ofAkter.command,Akter.query, orAkter.job, and ininitial.inputofAkter.make. An example isinput: { 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 importsSchemafromeffect.
akter/job-state-through-turn
- Rejects:
Akter.db,Akter.send,Akter.timer,Akter.start,Akter.cancel,Akter.signal, andActorStatein a job layer. Each passes inside therunhandler of<Actor>.turn({ from, to, run }), including anEffect.genorEffect.fnbody nested inrun. - Why: A job changes its actor’s state only inside
<Actor>.turn.akterdcommits the next state, the SQL writes, and the effects of a run as one step turn. - Fix: Move the call into the
runhandler, and return{ next, output }from it.
akter/no-raw-sql
- Rejects: A
sql<T>tagged template,Akter.sql, and a value fromeffect/sql,effect/unstable/sql,@effect/sql,@effect/sql-*,node:sqlite,bun:sqlite, orbetter-sqlite3. It also rejects a dynamicimport()of those modules. It checks actor handlers, job layers, and<Actor>.turnruns. - Why: A
sql<T>template casts unchecked rows toT. Handlers reach SQL only throughAkter.db, a typed drizzle database over the tables thatAkter.tabledeclares. - Fix: Declare the table with
Akter.table, and list it in the actor’stables. Query it withyield* Akter.db, such asdb.select().from(OrdersTable).where(eq(OrdersTable.id, id)).
akter/required-slots
- Rejects: An
Akter.makecall without one ofcallers,commands,initial,key,parent,queries,states, ortables. It also rejects an emptyfinal,jobs, orsecretsslot, 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: [], oroutput: Schema.Void. Delete an empty facet slot. - Member slots:
Akter.commandtakescallers,errors,from,input,output, andto.Akter.querytakescallers,errors,input,output, andstates.Akter.jobtakeserrors,from,input,output,patches, andto.
akter/state-machine-status
- Rejects: A field named
status,phase,state, orstagewhose schema is a string literal, a union of literals, or an enum. An example isstatus: Schema.Literals(["open", "paid"]). It checks everySchema.TaggedStruct, and everySchema.Structin thestatesslot ofAkter.make. - Why: A lifecycle inside one struct lets every handler read and write any status. Separate states let
Akter.makecheck each command’sfromandto. - Fix: Declare one
Schema.TaggedStructper value, such asOpenandPaid, and list them instates: [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"], andinitial: { to: "Open" }. A string insecretsorpatchespasses. - 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]forconst 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
runhandler of<Actor>.turn, everyActivitycall, such asActivity.make, andHttpClient. It also rejects the globalfetchand any use of a network module there. In an actor handler, it rejects a value fromeffect/workflowand calls toActivity. - Why: A turn run and a command or query handler are deterministic turns that
akterdcommits once. An external call inside them runs again on every replay. - Fix: Run the external call as an
Activity.makeblock in the job body before<Actor>.turn, and pass its result intorun. Move anActivityin an actor handler into a job layer. - Scope:
akter/actor-no-networkreports network I/O in actor handlers, so this rule reports network I/O only inrunhandlers. Arunhandler inside an actor handler counts as a turn run. Each case gets one report.