Types and namespaces

duck-iam ships its types inside per-module namespaces and its runtime values as flat names. This page is the map for 5.10.0: every exported namespace, its members, and the flat runtime exports, one line each, with the import path each comes from. Use it as the type-import contract when you write adapters, wrappers, or your own tooling on top of the engine.

Naming convention

Three rules hold across the whole package.

1. Interfaces carry the I prefix - IPolicy, IRule, IDecision, IAccessRequest, IConfig.
2. Type aliases stay bare - Effect, Operator, Mode, PolicyCombine, CombiningAlgorithm, ValidationCode.
3. Runtime values are flat and Iam-prefixed - IamEngine, IamMemoryAdapter, IamLRUCache, iamBuildPermissionKey. Free functions carry the prefix too (iamEvaluateFast, iamIndexPolicy, iamResolveValue), and constants use the screaming form (IAM_MAX_CONDITION_DEPTH). Namespaces are type-only; they add nothing to the bundle.

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

function decide(policy: AccessControl.IPolicy, req: IamRequest.IAccessRequest): AccessControl.IDecision {
  // ...
}

Namespaces exist so short member names can repeat without colliding. IConfig is a member of IamEngineTypes, IamHttp, IamRedis, IamDrizzle, IamRedisInvalidator, and IamMetrics; IResult is a member of both Explain and IamValidate. The namespace prefix is what disambiguates them at the call site.

Where each namespace lives

Namespaces are grouped by the exports entry that publishes them.

The root entry re-exports everything in @gentleduck/iam/core, so AccessControl through Evaluate are reachable from either specifier. IamValidate is a special case: core/index.ts re-exports the namespace as a type only and deliberately does not re-export the validator functions, so importing validatePolicy requires the @gentleduck/iam/core/validate subpath. Everything under adapters/*, server/*, client/*, invalidators/*, and observability/* is only reachable through its own subpath.

Core namespaces

AccessControl

import type { AccessControl } from '@gentleduck/iam' - the policy and decision vocabulary.

IamRequest

import type { IamRequest } from '@gentleduck/iam' - the request the engine evaluates.

IamPrimitives

import type { IamPrimitives } from '@gentleduck/iam' - the leaves of the type system.

IamClient

import type { IamClient } from '@gentleduck/iam' - permission-map keys shared by server and client.

IamAdapter

import type { IamAdapter } from '@gentleduck/iam' - the storage contract.

DotPath

import type { DotPath } from '@gentleduck/iam' - the type machinery behind typed field paths, typed $-references, and typed attribute keys. See typed context for how these are wired into the builders.

IamConfig

import type { IamConfig } from '@gentleduck/iam' - the shapes around createIam().

IamEngineTypes

import type { IamEngineTypes } from '@gentleduck/iam' - engine configuration and lifecycle. The class itself is the flat IamEngine; the namespace is suffixed Types to avoid the clash. Documented in depth under engine.

Evaluate

import type { Evaluate } from '@gentleduck/iam' - internals of the evaluation pass, exported so tooling can type against them.

Explain

import type { Explain } from '@gentleduck/iam' (values from @gentleduck/iam/core/explain) - the explain trace. See explain.

IamValidate

import type { IamValidate } from '@gentleduck/iam'; the validator functions come from @gentleduck/iam/core/validate. See validation.

IamError

import type { IamError } from '@gentleduck/iam' - the coded-error vocabulary every throw in the package uses instead of a raw Error.

Batch

import type { Batch } from '@gentleduck/iam' - per-row results for engine.admin's batch writes (assignRoles, revokeRoles, and similar).

Pending

import type { Pending } from '@gentleduck/iam' - cache invalidations and mutation events a transaction-bound engine holds until the caller's transaction commits.

Bound

import type { Bound } from '@gentleduck/iam' - the transaction-bound view engine.withTransaction(client) returns. See engine methods.

Integration namespaces

Each integration subpath publishes its own option-bag namespace. All are type-only.

Flat exports

Everything below is exported under its own name, not through a namespace.

From @gentleduck/iam and @gentleduck/iam/core

The condition engine no longer throws its own error classes - a malformed condition group, a type-mismatched operand, a refused matches pattern, an oversized regex input, and a $-sourced pattern each throw the coded IamError with one of IAM_CONDITION_GROUP_INVALID, IAM_CONDITION_OPERAND_TYPE, IAM_CONDITION_PATTERN_REFUSED, IAM_CONDITION_REGEX_INPUT_TOO_LARGE, or IAM_CONDITION_USER_SOURCED_PATTERN. Catch with hasIamErrorCode(err, '<code>') and read the detail off metaOf(err, '<code>'), not off the message.

From @gentleduck/iam/core/validate

From the integration subpaths

Gotchas

• IamValidate is a type-only re-export from core. core/index.ts exports the namespace but not validatePolicy; the functions live behind @gentleduck/iam/core/validate so the validator chunk stays opt-in.
• createIam() reaches the validator anyway. The object it returns closes over validatePolicy and validateRoles, so once you call createIam the validator code is retained even though you never imported the subpath. If bundle size is the priority, use the untyped builders and validate at an explicit boundary.
• IResult and IConfig are ambiguous without their namespace. Never destructure them into a bare local alias in shared code.
• The Types suffix appears once. IamEngineTypes is the only namespace named for its class rather than its domain, because IamEngine is a runtime class occupying the flat name.

See also

• createIam() - the factory whose generics thread these types through every builder.
• Typed context - how DotPath turns your context interface into autocomplete.
• Engine methods - the IamEngineTypes.IConfig and IAdmin surfaces in use.
• Adapters - implementing IamAdapter.IAdapter.