@locel/adonisjs

The AdonisJS integration. A provider, a defineConfig, a Lucid shortcut, routes and commands. It contains no sync logic — everything of substance lives in @locel/server, and this package wires it to the framework.

Status: Built. Provider, config, manager, routes, commands, stores.lucid and withSync, and the routes are exercised over real HTTP against a real AdonisJS server. The configure stubs are the one part with no test behind them — they run once, at node ace add, and what they write is checked by reading it.

Installation

node ace add @locel/adonisjs

defineConfig(config)

import env from '#start/env'
import { defineConfig, stores, type InferLocelStores } from '@locel/adonisjs'
import schema from '#sync/schema'

const locelConfig = defineConfig({
  schema,
  default: env.get('LOCEL_STORE'),
  stores: {
    lucid: stores.lucid({ connectionName: 'postgres' }),
    sqlite: stores.sqlite({ path: env.get('LOCEL_DB_PATH') }),
    memory: stores.memory(),
  },
  partitionColumns: ['workspaceId'],
  partition: (ctx) => ({ workspaceId: ctx.auth.getUserOrFail().currentWorkspaceId }),
  principal: (ctx) => ctx.auth.getUserOrFail().id,
  policies: {
    todos: {
      write: (mutation, ctx) => mutation.type !== 'delete' || ctx.auth.getUserOrFail().isAdmin,
    },
  },
  prefix: '/sync',
})

export default locelConfig

declare module '@locel/adonisjs/types' {
  export interface LocelStoresList extends InferLocelStores<typeof locelConfig> {}
}

partitionColumns and partition are both required, and they answer different questions. The authority needs the names before any request exists — it checks at boot that every collection carries all of them, and that none of them is sealed. partition returns values, and values only exist once somebody has asked for something.

defineConfig returns its argument unchanged; its only job is inference. The declare module block feeds your config's shape back into locel's types, so locel.use('sqlite') autocompletes and an unknown name is a compile error.

Stores

stores.lucid({ connectionName?, tablePrefix? })   // your application database
stores.knex(knex, { tablePrefix? })               // an app-owned Knex instance
stores.kysely(db, { tablePrefix? })               // an app-owned Kysely instance
stores.sqlite({ path })                           // a database locel owns (preset over kysely)
stores.memory()                                   // tests (preset over sqlite, in memory)

Each returns a config provider rather than a store. Nothing is constructed while config/locel.ts is being evaluated; the container resolves the connection during boot, and the driver is imported only if the store is the one you selected. That is what lets stores.lucid() depend on @adonisjs/lucid without @locel/adonisjs importing it.

stores.lucid

There is no Lucid driver. stores.lucid() resolves lucid.db, takes the connection's getWriteClient() — the underlying Knex instance — and hands it to stores.knex in @locel/server:

database(config) {
  return configProvider.create(async (app) => {
    const db = await app.container.make('lucid.db')
    const connection = db.connection(config?.connectionName ?? db.primaryConnectionName)
    return stores.knex(connection.getWriteClient(), config)
  })
}

So every dialect Lucid supports is supported here, through one adapter, and the integration package keeps holding no logic.

Synced rows live in your own tables, and the rest of your application reads them with Lucid as usual. The store needs to know which columns carry the row header, which the withSync mixin declares:

import { compose } from '@adonisjs/core/helpers'
import { BaseModel, column } from '@adonisjs/lucid/orm'
import { withSync } from '@locel/adonisjs'
import { todos } from '#sync/schema'

export default class Todo extends compose(BaseModel, withSync(todos)) {
  @column({ isPrimary: true })
  declare id: string

  @column()
  declare workspaceId: string

  @column()
  declare title: string
}

The mixin adds the row header columns, the tombstone filter on default queries, and a static syncCollection the store reads. It does not change how you write to the model outside sync — a server-side write through Lucid is stamped with the next sequence number and broadcast, so an admin action shows up on every connected client without going through the sync path.

Container service

import locel from '@locel/adonisjs/services/main'

const session = await locel.session(ctx)
await session.push({ transactions })

await locel.use('memory')   // a different store, typed from your config
await locel.authority       // the underlying Authority

All three are async: an authority is built the first time its store is asked for, and building one resolves a config provider from the container.

Routes

The provider registers, under prefix:

They are ordinary routes. Apply your own middleware:

import locelRoutes from '@locel/adonisjs/routes'

locelRoutes().use(middleware.auth())

Authentication is yours. locel never sees a credential — it sees the scope your partition function returned.

Commands

locel:doctor exits non-zero on any difference. Run it in CI — a schema and a database that disagree is the failure that reaches production silently.

Testing

import { test } from '@japa/runner'
import locel from '@locel/adonisjs/services/main'

test('a write is refused outside the partition', async ({ assert }) => {
  const session = (await locel.use('memory')).session({
    scope: { workspaceId: 'w1' },
    principal: 'u_1',
    writer: 'w_test',
  })

  const { results } = await session.push({
    transactions: [transactionFor({ workspaceId: 'w2' })],
  })

  assert.equal(results[0].outcome, 'rejected')
  assert.equal(results[0].code, 'E_ROW_OUTSIDE_PARTITION')
})

push resolves whatever happened; a refused transaction is a rejected outcome in results, not a thrown error. Only a malformed request throws.

Related

• @locel/server — everything this package wraps
• Partitions guide
• Error codes