Adapters overview

An adapter is the only thing IamEngine requires. It is a plain object implementing IamAdapter.IAdapter: nineteen async methods, thirteen required and six optional, that read and write policies, roles, role assignments, and subject attributes. Evaluation, caching, role inheritance, scope resolution, explain traces, and timeouts all live in the engine, so an adapter never decides anything - it only stores and returns rows.

The three stores

IamAdapter.IAdapter is the intersection of three narrower interfaces, all generic over the same TAction, TResource, TRole, and TScope parameters your engine is typed with. You can accept the narrower interface in your own code when you only need one part.

IPolicyStore and IRoleStore are symmetrical CRUD surfaces keyed on id. ISubjectStore is the asymmetric one: getSubjectRoles returns global assignments only, while getSubjectScopedRoles returns the scoped ones, and the two must never overlap.

Six members carry a ?. Five live on ISubjectStore; withClient is declared on IAdapter itself, because re-binding to a driver handle is a property of the whole adapter rather than of one store.

import type { AccessControl, IamAdapter, IamPrimitives, IamRequest } from '@gentleduck/iam'

export interface IAdapter<
  TAction extends string = string,
  TResource extends string = string,
  TRole extends string = string,
  TScope extends string = string,
> extends IPolicyStore<TAction, TResource, TRole>,
    IRoleStore<TAction, TResource, TRole, TScope>,
    ISubjectStore<TRole, TScope> {
  withClient?(client: unknown): IAdapter<TAction, TResource, TRole, TScope>
}

Method reference

Every read method takes an optional IamAdapter.IReadOptions - currently just { signal?: AbortSignal }. Every method returns a promise.

Optional methods and their fallbacks

Omitting an optional method costs correctness nowhere - each one is either an optimisation the engine falls back for, or a capability the engine refuses outright rather than approximating:

• getSubjectScopedRoles absent - the engine has no scoped grants to merge. There is no error and no warning, so scope-aware evaluation degrades silently. All six shipped adapters implement it.
• updateAssignmentScope absent, or present and returning false - engine.admin.updateAssignmentScope(...) falls back to revokeRole + assignRole. Same end state, but you lose row identity (id, createdAt) and atomicity, and there is a window where the subject holds neither.
• assignRoleMany / revokeRoleMany absent - the engine loops per row instead of issuing one statement.
• getSubjectGrantBoundary absent - the engine caches the subject for the full cacheTTL instead of capping the entry at the next grant transition.
• withClient absent - engine.withTransaction(tx) throws, rather than silently writing outside the caller's transaction.

Which adapter implements what is declared once, in src/adapters/__compliance__/optional-support.ts, and checked against the real prototypes by optional-method-matrix.test.ts - so a method that disappears turns a row red instead of turning asserting tests into skipped ones. Choosing an adapter reproduces the table.

Thrown errors

The engine treats any rejection from an adapter as a hard failure and routes it through its fail-closed path (onError, then the configured defaultEffect). These throws are expected, and the last two come from the engine rather than from the adapter:

The shape guard on setSubjectAttributes is shared: every built-in adapter calls the same iamAssertAttributesParam helper, so a string like 'admin=true' cannot spread into per-character attribute keys. A rejected call leaves existing attributes untouched.

Concurrency expectations

The engine calls adapters concurrently and expects them to cope; it does not serialise writes for you.

• Reads are collapsed, not serialised. The engine keeps an in-flight map, so 500 simultaneous cold requests for one subject produce one getSubjectRoles, not 500. maxConcurrentSubjectLoads (default 512; 0 restores unbounded) caps how many distinct subjects may be loading at once; past the cap a new load rejects with a message containing subject load shed.
• Writes are not transactional across methods by default. engine.admin calls one adapter method per operation. An adapter implementing withClient can join a caller's transaction through engine.withTransaction(tx); drizzle and prisma do, and the other four throw there rather than writing outside it.
• setSubjectAttributes is a read-modify-write in every built-in adapter, and it is not wrapped in a transaction. Two concurrent merges to the same subject can lose one of them. Use an atomic merge in your backend if that matters (jsonb ||, a Mongo $set, a DynamoDB UpdateExpression).
• Cancellation is best-effort. Adapters that can honour opts.signal should; adapters that cannot (memory, file) may ignore it. The engine releases the request either way when adapterTimeoutMs (default 5000, 0 disables) elapses - the orphaned work just runs to completion in the background.

Built-in adapters

Every one of them also exports a lowercase factory (iamMemoryAdapter, iamFileAdapter, iamPrismaAdapter, iamDrizzleAdapter, iamRedisAdapter, iamHttpAdapter) for callers who prefer functions to new. The factories take the same arguments as the constructors.

Where an adapter sits

Adapters are behind two cache layers, which is why a warm process barely touches storage.

Both the subject LRU (maxCacheSize, default 1000 entries) and the policy/role caches expire after cacheTTL seconds (default 60; 0 disables caching entirely and makes every call hit the adapter). Writes through engine.admin invalidate the matching cache immediately, so an adapter never has to publish anything itself - unless you run more than one process, in which case wire the Redis invalidator.

Swapping adapters

Adapters are interchangeable by construction: engine, builder, server middleware, and client code do not know which one is underneath. Migration is data movement only.

import { IamEngine } from '@gentleduck/iam'
import { IamMemoryAdapter } from '@gentleduck/iam/adapters/memory'

// development
const adapter = new IamMemoryAdapter({ roles, policies, assignments: { 'user-1': ['admin'] } })
const engine = new IamEngine({ adapter, defaultEffect: 'deny' })

const allowed = await engine.can('user-1', 'read', { type: 'post', attributes: {} })

Swapping IamMemoryAdapter for IamDrizzleAdapter changes those two lines and nothing else. Choosing an adapter walks the trade-offs.

Verifying an adapter

Every shipped adapter runs the same vitest matrix, runAdapterCompliance(name, factory, { supports }), which pins the cross-backend contract: empty stores return [] and null, saves upsert, deletes are idempotent, deleteRole cascades, getSubjectRoles returns only unscoped roles, getSubjectScopedRoles returns only scoped ones, revoke with a scope removes just that grant while revoke without one removes them all, and setSubjectAttributes merges rather than replaces. supports declares which optional methods you implement; clauses for the rest are never registered, so an unimplemented method cannot show up as a pass. A second suite, runEngineCapabilityCompliance, runs the same behaviour one rung up through engine.admin, where the fallbacks live. See Custom adapter.

See also

• Choosing an adapter - feature matrix, decision tree, FAQ
• Custom adapter - implement the interface for any backend
• Caching - what the engine keeps in front of your adapter
• Admin API - the write path that calls these methods