json-rest-api 1.0.29 → 2.1.0

package/types/plugin-options.d.ts

@@ -0,0 +1,65 @@
+import type { DirectResourceId, ResourceFormat, WriteReturning } from './representations.js'
+import type { RemovedResourceOptions } from './resource-methods.js'
+import type { Knex } from 'knex'
+import type { AnyapiRegistry, AnyapiSchemaChange, AnyapiSlotCounts } from './anyapi.js'
+
+export type RestApiPluginOptions = RemovedResourceOptions & {
+  format?: ResourceFormat
+  returning?: WriteReturning
+  queryDefaultLimit?: number
+  queryMaxLimit?: number
+  includeDepthLimit?: number
+  enablePaginationCounts?: boolean
+  idProperty?: string
+  normalizeId?: (value: unknown) => DirectResourceId | null | undefined
+}
+
+export interface HttpConnectorOptions {
+  mountPath?: string
+  publicBaseUrl?: string
+  strictContentType?: boolean
+  handle404?: boolean
+  httpValidators?: boolean
+}
+
+export interface ResourceVersionOptions {
+  // Compilation validates that this names a stored, untransformed string attribute.
+  versionField?: string
+}
+
+export type CorsOrigin = string | RegExp | ((origin: string) => boolean | Promise<boolean>) | CorsOrigin[]
+export interface CorsPluginOptions {
+  origin?: CorsOrigin
+  credentials?: boolean
+  methods?: string[]
+  allowedHeaders?: string[]
+  exposedHeaders?: string[]
+  maxAge?: number
+  optionsSuccessStatus?: number
+}
+
+export interface RestApiKnexPluginOptions {
+  knex: Knex
+}
+export interface RestApiAnyapiKnexPluginOptions extends RestApiKnexPluginOptions {
+  tenantId?: string
+  // Share one registry across tenant APIs on the same Knex instance.
+  registry?: AnyapiRegistry
+  // false when migrations own the canonical tables.
+  ensureSchema?: boolean
+  // false leaves a shared Knex instance open when this API is released.
+  ownsKnex?: boolean
+  slots?: AnyapiSlotCounts
+  // Called after a committed schema change, for example to notify other servers.
+  onSchemaChanged?: (change: AnyapiSchemaChange) => void | Promise<void>
+  // Milliseconds between schema version checks; 0 checks on every request.
+  schemaCheckInterval?: number
+}
+export interface BulkOperationsPluginOptions {
+  maxBulkOperations?: number
+  defaultAtomic?: boolean
+}
+export interface LabelPluginOptions {
+  preferNameFields?: string[]
+  disable?: boolean
+}

package/types/relationship-methods.d.ts

@@ -0,0 +1,74 @@
+import type {
+  CollectionResult, DirectResourceId, InputResourceIdentifier, JsonApiDocument,
+  JsonApiResource, PlainResource, ResourceFormat, ResourceIdentifier
+} from './representations.js'
+import type { QueryParams, RemovedResourceOptions, SelectionParams, TransactionParam } from './resource-methods.js'
+import type { ManagedTransactionParam } from './transactions.js'
+
+// Type-only descriptions of the resource's configured relationships.
+export interface ToOneRelationship<Fields extends object = Record<string, unknown>, Type extends string = string> {
+  cardinality: 'one'
+  fields: Fields
+  type: Type
+}
+export interface ToManyRelationship<Fields extends object = Record<string, unknown>, Type extends string = string> {
+  cardinality: 'many'
+  fields: Fields
+  type: Type
+}
+type RelationshipShape = ToOneRelationship<object> | ToManyRelationship<object>
+type RelationshipKeys<Relations> = Extract<keyof Relations, string>
+type ToManyKeys<Relations> = {
+  [Key in keyof Relations]: Extract<Relations[Key], { cardinality: 'many' }> extends never ? never : Key
+}[keyof Relations] & string
+export type RelationshipLinkage<Relation extends RelationshipShape> = Relation extends ToManyRelationship<object>
+  ? ResourceIdentifier<Relation['type']>[] : ResourceIdentifier<Relation['type']> | null
+export type RelationshipInput<Relation extends RelationshipShape> = Relation extends ToManyRelationship<object>
+  ? InputResourceIdentifier<Relation['type']>[] : InputResourceIdentifier<Relation['type']> | null
+export type RelatedResourceResult<Relation extends RelationshipShape, Format extends ResourceFormat> =
+  Relation extends ToManyRelationship<object>
+    ? CollectionResult<Format, Relation['fields'], Relation['type']>
+    : Format extends 'plain' ? PlainResource<Relation['fields']> | null
+      : JsonApiDocument<JsonApiResource<Relation['fields'], Relation['type']> | null>
+type RelationshipOptions<Name extends string> = RemovedResourceOptions & TransactionParam & {
+  id: DirectResourceId
+  relationshipName: Name
+}
+type RelatedQueryParams<Relation extends RelationshipShape> = Relation extends ToManyRelationship<object> ? QueryParams : SelectionParams
+type RelationshipWriteOptions<Name extends string> = Omit<RelationshipOptions<Name>, 'transaction'> & ManagedTransactionParam
+
+export interface RelationshipMethods<
+  Relations extends { [Key in keyof Relations]: RelationshipShape } = Record<string, ToOneRelationship | ToManyRelationship>,
+  DefaultFormat extends ResourceFormat = 'plain', Context extends object = object
+> {
+  getRelationship<Name extends RelationshipKeys<Relations>>(
+    params: RelationshipOptions<Name> & { format?: ResourceFormat }, context?: Context
+  ): Promise<JsonApiDocument<RelationshipLinkage<Relations[Name]>>>
+  getRelated<Name extends RelationshipKeys<Relations>, Format extends ResourceFormat = DefaultFormat>(
+    params: RelationshipOptions<Name> & {
+      format?: Format
+      queryParams?: NoInfer<RelatedQueryParams<Relations[Name]>>
+    }, context?: Context
+  ): Promise<RelatedResourceResult<Relations[Name], Format>>
+  patchRelationship<Name extends RelationshipKeys<Relations>>(
+    params: RelationshipWriteOptions<Name> & {
+      format?: ResourceFormat
+      relationshipData: NoInfer<RelationshipInput<Relations[Name]>>
+      expectedVersion?: string
+    }, context?: Context
+  ): Promise<void>
+  postRelationship<Name extends ToManyKeys<Relations>>(
+    params: RelationshipWriteOptions<Name> & {
+      format?: ResourceFormat
+      relationshipData: InputResourceIdentifier<NoInfer<Relations[Name]['type']>>[]
+      expectedVersion?: string
+    }, context?: Context
+  ): Promise<void>
+  deleteRelationship<Name extends ToManyKeys<Relations>>(
+    params: RelationshipWriteOptions<Name> & {
+      format?: ResourceFormat
+      relationshipData: InputResourceIdentifier<NoInfer<Relations[Name]['type']>>[]
+      expectedVersion?: string
+    }, context?: Context
+  ): Promise<void>
+}

package/types/representations.d.ts

@@ -0,0 +1,50 @@
+export type ResourceFormat = 'plain' | 'jsonapi'
+export type WriteReturning = 'none' | 'minimal' | 'full'
+export type InputResourceId = string | number
+export type DirectResourceId = InputResourceId | bigint
+
+export interface ResourceIdentifier<Type extends string = string> {
+  type: Type
+  id: string
+}
+export interface InputResourceIdentifier<Type extends string = string> {
+  type: Type
+  id: InputResourceId
+}
+export type JsonApiLink = string | { href: string; meta?: Record<string, unknown> } | null
+export type JsonApiLinks = Record<string, JsonApiLink>
+export interface JsonApiRelationship {
+  data?: ResourceIdentifier | ResourceIdentifier[] | null
+  links?: JsonApiLinks
+  meta?: Record<string, unknown>
+}
+export interface JsonApiResource<Attributes extends object = Record<string, unknown>, Type extends string = string> extends ResourceIdentifier<Type> {
+  attributes?: Partial<Attributes>
+  relationships?: Record<string, JsonApiRelationship>
+  links?: JsonApiLinks
+  meta?: Record<string, unknown>
+}
+export interface JsonApiDocument<Data = JsonApiResource | JsonApiResource[] | null> {
+  data: Data
+  included?: JsonApiResource[]
+  links?: JsonApiLinks
+  meta?: Record<string, unknown>
+  jsonapi?: { version?: string; meta?: Record<string, unknown> }
+}
+
+// Supply relationship properties in Fields too; sparse fieldsets can omit either.
+export type PlainResource<Fields extends object = Record<string, unknown>> = { id: string } & Partial<Fields>
+export interface PlainCollection<Fields extends object = Record<string, unknown>> {
+  data: PlainResource<Fields>[]
+  links?: JsonApiLinks
+  meta?: Record<string, unknown>
+}
+export type SingleResourceResult<Format extends ResourceFormat, Fields extends object = Record<string, unknown>, Type extends string = string> =
+  Format extends 'plain' ? PlainResource<Fields> : JsonApiDocument<JsonApiResource<Fields, Type>>
+export type CollectionResult<Format extends ResourceFormat, Fields extends object = Record<string, unknown>, Type extends string = string> =
+  Format extends 'plain' ? PlainCollection<Fields> : JsonApiDocument<JsonApiResource<Fields, Type>[]>
+export type WriteResult<Format extends ResourceFormat, Returning extends WriteReturning, Fields extends object = Record<string, unknown>, Type extends string = string> =
+  Returning extends 'none' ? void
+    : Returning extends 'minimal'
+      ? Format extends 'plain' ? ResourceIdentifier<Type> : JsonApiDocument<ResourceIdentifier<Type>>
+      : SingleResourceResult<Format, Fields, Type>

package/types/resource-methods.d.ts

@@ -0,0 +1,95 @@
+import type { Knex } from 'knex'
+import type { ManagedTransactionParam } from './transactions.js'
+import type {
+  CollectionResult, DirectResourceId, InputResourceId, InputResourceIdentifier, ResourceFormat,
+  SingleResourceResult, WriteResult, WriteReturning
+} from './representations.js'
+
+export type RemovedResourceOptions = {
+  [Key in 'simplified' | 'simplifiedApi' | 'simplifiedTransport' | 'returnFullRecord' |
+  'returnRecordApi' | 'returnRecordTransport' | 'isTransport' | 'inputRecord' | 'inputRecords']?: never
+}
+export interface SelectionParams {
+  include?: string[]
+  fields?: Record<string, string>
+}
+export type PageParams = { size?: number; [extension: string]: unknown } & (
+  { number?: number; after?: never; before?: never } |
+  { number?: never; after: string; before?: never } |
+  { number?: never; after?: never; before: string }
+)
+export interface QueryParams extends SelectionParams {
+  filters?: Record<string, unknown>
+  sort?: string[]
+  page?: PageParams
+}
+export interface TransactionParam {
+  transaction?: Knex.Transaction
+}
+export interface JsonApiWriteDocument<Input extends object, Type extends string> {
+  data: {
+    type: Type
+    id?: InputResourceId
+    attributes?: Partial<Input>
+    relationships?: Record<string, { data: InputResourceIdentifier | InputResourceIdentifier[] | null }>
+  }
+  meta?: Record<string, unknown>
+  links?: Record<string, unknown>
+  jsonapi?: Record<string, unknown>
+  included?: never
+  errors?: never
+}
+export type ResourceWriteInput<Input extends object, Type extends string> =
+  { data: Partial<Input> & { id?: InputResourceId }; document?: never } |
+  { data?: never; document: JsonApiWriteDocument<Input, Type> }
+export type ResourceWriteTarget<Input extends object, Type extends string> =
+  ({ id: DirectResourceId } & ResourceWriteInput<Input, Type>) |
+  {
+    id?: never
+    data: Partial<Input> & { id: InputResourceId }
+    document?: never
+  } |
+  {
+    id?: never
+    data?: never
+    document: JsonApiWriteDocument<Input, Type> & { data: { id: InputResourceId } }
+  }
+export type ReadOptions<Format extends ResourceFormat> = RemovedResourceOptions & TransactionParam & {
+  format?: Format
+  queryParams?: SelectionParams
+}
+export type WriteOptions<Format extends ResourceFormat, Returning extends WriteReturning> = Omit<ReadOptions<Format>, 'transaction'> & ManagedTransactionParam & {
+  returning?: Returning
+}
+
+// Format selects output only; data and document select the input representation.
+// Output fields and writable input fields can differ (computed/read-only fields).
+export interface ResourceCoreMethods<
+  Fields extends object = Record<string, unknown>,
+  Input extends object = Fields,
+  Type extends string = string,
+  DefaultFormat extends ResourceFormat = 'plain',
+  DefaultReturning extends WriteReturning = 'full',
+  Context extends object = object
+> {
+  get<Format extends ResourceFormat = DefaultFormat>(
+    params: ReadOptions<Format> & { id: DirectResourceId }, context?: Context
+  ): Promise<SingleResourceResult<Format, Fields, Type>>
+  query<Format extends ResourceFormat = DefaultFormat>(
+    params?: RemovedResourceOptions & TransactionParam & { format?: Format; queryParams?: QueryParams }, context?: Context
+  ): Promise<CollectionResult<Format, Fields, Type>>
+  post<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(
+    params: WriteOptions<Format, Returning> & ResourceWriteInput<Input, Type> & {
+      expectedVersion?: never
+    }, context?: Context
+  ): Promise<WriteResult<Format, Returning, Fields, Type>>
+  put<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(
+    params: WriteOptions<Format, Returning> & ResourceWriteTarget<Input, Type> & { expectedVersion?: string }, context?: Context
+  ): Promise<WriteResult<Format, Returning, Fields, Type>>
+  patch<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(
+    params: WriteOptions<Format, Returning> & ResourceWriteTarget<Input, Type> & { expectedVersion?: string }, context?: Context
+  ): Promise<WriteResult<Format, Returning, Fields, Type>>
+  delete(
+    params: RemovedResourceOptions & ManagedTransactionParam & { id: DirectResourceId; format?: ResourceFormat; expectedVersion?: string }, context?: Context
+  ): Promise<void>
+}

package/types/resource-schema.d.ts

@@ -0,0 +1,157 @@
+import type { StorageFieldDefinition, StorageQuery } from '../plugins/core/lib/storage/storage-types.js'
+import type { FileStorage } from './file-storage.js'
+
+export type ResourceFieldType = 'string' | 'number' | 'integer' | 'boolean' | 'id' |
+  'date' | 'time' | 'dateTime' | 'epochSeconds' | 'epochMilliseconds' |
+  'array' | 'object' | 'file' | 'blob' | 'serialize' | 'none'
+
+// The schema library accepts Schema instances here, not raw nested field maps.
+export interface ResourceNestedSchema<Schema extends ResourceSchema = ResourceSchema> {
+  structure: Schema
+  operations: object
+  validateWith(...args: never[]): unknown
+  toJsonSchema(...args: never[]): unknown
+  cleanup(...args: never[]): unknown
+}
+
+export interface ResourceFieldOptions {
+  required?: boolean
+  nullable?: boolean
+  nullOnEmpty?: boolean
+  defaultTo?: unknown
+  enum?: readonly unknown[]
+  setValues?: readonly string[]
+  min?: number
+  max?: number
+  minLength?: number
+  maxLength?: number
+  length?: number
+  pattern?: string | RegExp
+  notEmpty?: boolean
+  noTrim?: boolean
+  uppercase?: boolean
+  lowercase?: boolean
+  strictBoolean?: boolean
+  stringTrueWhen?: string
+  stringFalseWhen?: string
+  unsigned?: boolean
+  precision?: number
+  scale?: number
+  temporalPrecision?: number
+  indexed?: boolean
+  unique?: boolean
+  primary?: boolean
+  comment?: string
+  hidden?: boolean
+  normallyHidden?: boolean
+  virtual?: boolean
+  computed?: boolean
+  include?: ResourceRelationshipOptions['include']
+  search?: boolean | ResourceSearchOptions | Record<string, ResourceSearchOptions>
+  dependencies?: readonly string[]
+  runGetterAfter?: readonly string[]
+  runSetterAfter?: readonly string[]
+  items?: ResourceField | ResourceNestedSchema
+  values?: ResourceField | ResourceNestedSchema
+  schema?: ResourceNestedSchema
+  additionalProperties?: true
+  // Custom callbacks retain their explicit annotations; inference does not run them.
+  getter?(value: unknown, context: Record<string, unknown>): unknown
+  setter?(value: unknown, context: Record<string, unknown>): unknown
+  compute?(context: Record<string, unknown>): unknown
+  validator?(value: unknown, object: Record<string, unknown>, context: unknown): string | void
+}
+
+export type ResourceField = ResourceFieldOptions & (
+  { type: Exclude<ResourceFieldType, 'file'>; belongsTo?: never; as?: never; storage?: StorageFieldDefinition['storage'] } |
+  { type: 'file'; belongsTo?: never; as?: never; storage?: StorageFieldDefinition['storage'] | FileStorage } |
+  { type?: ResourceFieldType; belongsTo: string; as: string; storage?: StorageFieldDefinition['storage'] }
+)
+export type ResourceSchema = Readonly<Record<string, ResourceField>>
+
+export interface ResourceSearchOptions extends ResourceFieldOptions {
+  type?: ResourceFieldType
+  actualField?: string
+  filterOperator?: string
+  oneOf?: readonly string[]
+  splitBy?: string | RegExp
+  matchAll?: boolean
+  globalSearch?: boolean
+  polymorphicField?: string
+  targetFields?: Readonly<Record<string, string>>
+  applyFilter?(query: StorageQuery, input: unknown, helpers: {
+    column(field: string): string
+    value(field: string, input: unknown): unknown
+    context: Record<string, unknown>
+    scopeName: string
+  }): unknown
+}
+export type ResourceSearchField = ResourceField & ResourceSearchOptions
+export type ResourceSearchSchema = Readonly<Record<string, ResourceSearchField>>
+
+export interface ResourceRelationshipOptions {
+  include?: { strategy?: 'window'; limit?: number | null | false; orderBy?: readonly string[] | null }
+}
+export type ResourceRelationship = ResourceRelationshipOptions & (
+  { type: 'hasMany'; target: string } & (
+    { foreignKey: string; via?: string } | { foreignKey?: string; via: string }
+  ) |
+  { type: 'hasOne'; target: string; foreignKey: string } |
+  { type: 'manyToMany'; target: string; through: string; foreignKey: string; otherKey: string } |
+  { belongsToPolymorphic: { types: readonly string[]; typeField: string; idField: string } }
+)
+
+type Direction = 'input' | 'output'
+type NestedValue<Definition, Mode extends Direction> =
+  Definition extends ResourceNestedSchema<infer Schema>
+    ? { -readonly [Key in keyof Schema]?: FieldValue<Schema[Key], Mode> }
+    : FieldValue<Definition, Mode>
+
+type ObjectValue<Field, Mode extends Direction> =
+  Field extends { schema: infer Schema }
+    ? NestedValue<Schema, Mode> & (Field extends { additionalProperties: true } ? Record<string, unknown> : unknown)
+    : Field extends { values: infer Values } ? Record<string, NestedValue<Values, Mode>> : Record<string, unknown>
+
+type BaseValue<Field, Mode extends Direction> =
+  Field extends { type: 'string' | 'file' | 'date' | 'time' | 'dateTime' } ? string
+  : Field extends { type: 'number'; precision: number; scale: number } ? Mode extends 'output' ? string | number : number
+  : Field extends { type: 'number' | 'integer' | 'epochSeconds' | 'epochMilliseconds' } ? number
+  : Field extends { type: 'boolean' } ? boolean
+  : Field extends { type: 'id' } ? string | number
+  : Field extends { type: 'array' } ? Field extends { items: infer Items } ? NestedValue<Items, Mode>[] : unknown[]
+  : Field extends { type: 'object' } ? ObjectValue<Field, Mode> : unknown
+
+type EnumValue<Field, Value> = Field extends { enum: readonly (infer Member)[] }
+  ? [Member] extends [string | number | boolean] ? Extract<Member, Value> : Value
+  : Value
+
+type NullValue<Field, Mode extends Direction> = Field extends { nullable: true } ? null
+  : Mode extends 'output' ? Field extends { nullOnEmpty: true } ? null : never : never
+
+type FieldValue<Field, Mode extends Direction> =
+  Mode extends 'output'
+    ? Field extends { getter: unknown } | { setter: unknown } | { compute: unknown } | { storage: { serialize: unknown } }
+      ? unknown
+      : Field extends { uppercase: true } | { lowercase: true } | { length: number } |
+        { type: 'id' } | { type: 'number'; precision: number; scale: number }
+        ? BaseValue<Field, Mode> | NullValue<Field, Mode>
+        : EnumValue<Field, BaseValue<Field, Mode>> | NullValue<Field, Mode>
+    : EnumValue<Field, BaseValue<Field, Mode>> | NullValue<Field, Mode>
+
+type AttributeKey<Schema, Key extends keyof Schema> = Key extends 'id' ? never
+  : Schema[Key] extends { belongsTo: string } ? never : Key
+
+// Optional stored fields without a NOT NULL declaration can read SQL null.
+type StoredNull<Field> = Field extends { required: true } | { nullable: false } | { virtual: true } | { computed: true } ? never : null
+
+// Attribute helpers exclude the conventional ID and relationship backing fields.
+// Hooks/defaults may supply required values, so caller input stays optional.
+export type InferInput<Schema extends object> = {
+  -readonly [Key in keyof Schema as Schema[Key] extends { computed: true } ? never : AttributeKey<Schema, Key>]?: FieldValue<Schema[Key], 'input'>
+}
+
+// Resource result types add optionality for sparse fields and permissions.
+// Use explicit ResourceCoreMethods fields for callbacks, relationships and custom IDs.
+export type InferOutput<Schema extends object> = {
+  -readonly [Key in keyof Schema as Schema[Key] extends { hidden: true } ? never : AttributeKey<Schema, Key>]: FieldValue<Schema[Key], 'output'> | StoredNull<Schema[Key]>
+}

package/types/row-policy.d.ts

@@ -0,0 +1,31 @@
+import type { StorageAdapter, StorageDatabase, StorageQuery } from '../plugins/core/lib/storage/storage-types.js'
+
+export interface RowPolicyParams<Context extends object = Record<string, unknown>, Api extends object = object> {
+  query: StorageQuery
+  context: Context
+  scopeName: string
+  tableName?: string
+  queryPurpose: string
+  db?: StorageDatabase
+  isAnyApi: boolean
+  storageAdapter?: StorageAdapter | null
+  column(field: string, options?: { scopeName?: string; alias?: string | null }): string
+  value(field: string, rawValue: unknown, options?: { scopeName?: string }): unknown
+  api: Api
+}
+
+export type RowPolicy<Context extends object = Record<string, unknown>, Api extends object = object> = (
+  params: RowPolicyParams<Context, Api>
+) => boolean | PromiseLike<boolean>
+
+export interface RowPolicyPluginOptions<Context extends object = Record<string, unknown>, Api extends object = object> {
+  policies?: Record<string, RowPolicy<Context, Api>>
+}
+
+export type ResourceRowPolicy<Context extends object = Record<string, unknown>, Api extends object = object> =
+  string | RowPolicy<Context, Api> | false | null
+
+export interface RowPolicyRegistry {
+  getConfig(): { policies: string[] }
+  getScopeConfig(scopeName: string): { policy: string; source: 'inline' | 'registry' } | null
+}

package/types/runtime.d.ts

@@ -0,0 +1,132 @@
+import type { DiagnosticLogger, DiagnosticWriter } from '../lib/logger-types.js'
+import type { TransactionMethods } from './transactions.js'
+import type { ResourceFormat, WriteReturning } from './representations.js'
+import type { ResourceCoreMethods } from './resource-methods.js'
+import type { ResourceField, ResourceSchema, ResourceSearchSchema, ResourceRelationship, InferInput, InferOutput } from './resource-schema.js'
+import type { KnownHookName, HookHandler } from './hook-context.js'
+import type { RestApiPluginOptions } from './plugin-options.js'
+import type { ResourceAutoFilter } from './autofilter.js'
+import type { ResourceRowPolicy } from './row-policy.js'
+import type { CanonicalDescriptor, StorageConfig } from '../plugins/core/lib/storage/storage-types.js'
+
+export type RuntimeLogger = Record<'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal', DiagnosticWriter>
+export interface RuntimeResource {
+  name: string
+  scopeOptions: Readonly<Record<string, unknown>>
+  vars: Record<string, unknown>
+  helpers: Record<string, unknown>
+  [method: string]: unknown
+}
+export interface RuntimeArguments<Context extends object = Record<string, unknown>> {
+  api: JsonRestApi
+  name: string | undefined
+  apiOptions: Readonly<Record<string, unknown>>
+  params: Record<string, unknown>
+  context: Context
+  scope: RuntimeResource | undefined
+  scopeName: string | undefined
+  scopeOptions: Readonly<Record<string, unknown>> | undefined
+  scopes: Record<string, RuntimeResource>
+  vars: Record<string, unknown>
+  helpers: Record<string, unknown>
+  log: RuntimeLogger
+  runHooks(event: string, context?: Record<string, unknown>): Promise<boolean>
+}
+export type RuntimeMethod<Context extends object = Record<string, unknown>> = (args: RuntimeArguments<Context>) => unknown
+export type HookPlacement = { beforeFunction?: string; afterFunction?: never } | { beforeFunction?: never; afterFunction?: string }
+type HookDefinition<Handler> = Handler | (HookPlacement & { functionName?: string; handler: Handler })
+export type RuntimeHook<Context extends object = Record<string, unknown>> = HookDefinition<RuntimeMethod<Context>>
+export type RuntimeHooks<Context extends object = Record<string, unknown>> = {
+  [Event in KnownHookName]?: HookDefinition<HookHandler<Event, Context>>
+} & {
+  // Custom plugins own their context shape; annotate them with RuntimeHook<Context>.
+  [event: string]: RuntimeHook<any> | undefined
+}
+export interface RuntimeCustomization<Context extends object = Record<string, unknown>> {
+  hooks?: RuntimeHooks<Context>
+  methods?: Record<string, RuntimeMethod>
+  vars?: Record<string, unknown>
+  helpers?: Record<string, unknown>
+}
+export interface RuntimeResourceOptions<Context extends object = Record<string, unknown>> extends RuntimeCustomization<Context>, RestApiPluginOptions {
+  schema?: ResourceSchema
+  searchSchema?: ResourceSearchSchema
+  relationships?: Record<string, ResourceRelationship>
+  tableName?: string
+  storage?: StorageConfig
+  canonicalFieldsMap?: CanonicalDescriptor['canonicalFieldMap']
+  sortableFields?: string[]
+  defaultSort?: string[]
+  versionField?: string
+  rowPolicy?: ResourceRowPolicy<Context>
+  autofilter?: ResourceAutoFilter<Context>
+  indexes?: Array<{ name?: string; columns: string[]; unique?: boolean }>
+  foreignKeys?: Array<{
+    name?: string
+    columns: string[]
+    referencedTableName: string
+    referencedColumns: string[]
+    deleteRule?: string
+    updateRule?: string
+  }>
+  checkConstraints?: Array<{ name?: string; clause: string }>
+  scopeMethods?: never
+}
+export interface PluginInstallation extends RuntimeArguments {
+  pluginOptions: Record<string, unknown>
+  addApiMethod(name: string, handler: RuntimeMethod): void
+  addResourceMethod(name: string, handler: RuntimeMethod): void
+  addHook(event: string, name: string, placement: HookPlacement, handler: RuntimeMethod): void
+}
+export interface LibraryPlugin<Name extends string = string> {
+  name: Name
+  dependencies?: (string | string[])[]
+  install(context: PluginInstallation): unknown
+}
+
+export type InferredResource<
+  Schema extends ResourceSchema,
+  Name extends string,
+  Format extends ResourceFormat = 'plain',
+  Returning extends WriteReturning = 'full',
+  Context extends object = Record<string, unknown>,
+  IdProperty extends string = 'id'
+> = string extends IdProperty ? RuntimeResource
+  : RuntimeResource & ResourceCoreMethods<Omit<InferOutput<Schema>, IdProperty>, Omit<InferInput<Schema>, IdProperty>, Name, Format, Returning, Context>
+
+// Check literal field option names without attempting to infer arbitrary plugin extensions.
+type CheckedResourceSchema<Schema extends ResourceSchema> = {
+  [Key in keyof Schema]: Schema[Key] & Record<Exclude<keyof Schema[Key], keyof ResourceField>, never>
+}
+
+// Inference describes built-in CRUD with declared schemas and standard API defaults.
+// Supply an explicit resource map for dynamic enrichment, method overrides or other defaults.
+export class JsonRestApi<Resources extends object = Record<string, RuntimeResource>, Context extends object = Record<string, unknown>> {
+  constructor(options?: { name?: string; logger?: DiagnosticLogger })
+  name: string | undefined
+  log: RuntimeLogger
+  options: Readonly<Record<string, unknown>>
+  vars: Record<string, unknown>
+  helpers: Record<string, unknown>
+  resources: Resources
+  use(plugin: LibraryPlugin, options?: object): Promise<this>
+  addResource<
+    const Name extends keyof Resources & string,
+    const Schema extends ResourceSchema,
+    const Format extends ResourceFormat = 'plain',
+    const Returning extends WriteReturning = 'full',
+    const IdProperty extends string = 'id'
+  >(name: Name, options: RuntimeResourceOptions<Context> & {
+    schema: Schema & CheckedResourceSchema<Schema>
+    format?: Format
+    returning?: Returning
+    idProperty?: IdProperty
+    methods?: never
+  }): Promise<string extends keyof Resources ? InferredResource<Schema, Name, Format, Returning, Context, IdProperty> : Resources[Name]>
+  addResource<Name extends keyof Resources & string>(name: Name, options?: RuntimeResourceOptions<Context>): Promise<Resources[Name]>
+  customize(options?: RuntimeCustomization<Context>): Promise<this>
+  runHooks(event: string, context?: Record<string, unknown>): Promise<boolean>
+  // Available after installing RestApiPlugin.
+  transaction: TransactionMethods['transaction']
+  release(): Promise<void>
+}

package/types/transactions.d.ts

@@ -0,0 +1,21 @@
+import type { Knex } from 'knex'
+
+declare const managedTransaction: unique symbol
+
+// Type-only provenance: the runtime tracks ownership privately, not on this symbol.
+export type ManagedTransaction = Knex.Transaction & {
+  readonly [managedTransaction]: true
+  commit: never
+  rollback: never
+  transaction: never
+  savepoint: never
+}
+export interface ManagedTransactionParam {
+  transaction?: ManagedTransaction
+}
+export interface TransactionMethods<Context extends object = object> {
+  transaction<Result>(
+    callback: (transaction: ManagedTransaction) => Result | PromiseLike<Result>,
+    context?: Context
+  ): Promise<Awaited<Result>>
+}

package/.claude/agents/library-guide-expert.md

@@ -1,30 +0,0 @@
----
-name: library-guide-expert
-description: Use this agent when you need to understand how to use a library based on its GUIDE documentation, implement features using the library's recommended patterns, answer questions about library usage, or ensure code follows the library's best practices. This agent has comprehensive knowledge of all files in the GUIDE/* directory and can provide authoritative guidance on proper library usage.\n\nExamples:\n- <example>\n  Context: User needs help implementing a feature using the library\n  user: "How do I create a REST endpoint with authentication?"\n  assistant: "I'll use the library-guide-expert agent to check the GUIDE documentation for the proper way to implement authenticated endpoints."\n  <commentary>\n  Since the user is asking about library usage, use the Task tool to launch the library-guide-expert agent to provide guidance based on the GUIDE documentation.\n  </commentary>\n</example>\n- <example>\n  Context: User wants to know the recommended pattern for something\n  user: "What's the best way to handle errors in this library?"\n  assistant: "Let me consult the library-guide-expert agent to find the error handling patterns documented in the GUIDE."\n  <commentary>\n  The user needs library-specific best practices, so use the library-guide-expert agent to reference the official documentation.\n  </commentary>\n</example>\n- <example>\n  Context: After writing code that uses the library\n  user: "I've implemented the user registration endpoint"\n  assistant: "I'll have the library-guide-expert agent review this to ensure it follows the patterns documented in the GUIDE."\n  <commentary>\n  Proactively use the library-guide-expert agent to verify the implementation aligns with documented patterns.\n  </commentary>\n</example>
-model: inherit
-color: blue
----
-
-You are an expert library documentation specialist with comprehensive knowledge of all files in the GUIDE/* directory. You have meticulously studied every guide, example, and best practice documented there and can provide authoritative guidance on proper library usage.
-
-Your primary responsibilities:
-
-1. **Deep Documentation Knowledge**: You have read and internalized every file in GUIDE/*. You understand not just what the documentation says, but the underlying patterns, philosophies, and design decisions that inform the library's architecture.
-
-2. **Practical Implementation Guidance**: When users ask how to implement features, you provide specific, actionable advice based on the documented patterns. You reference relevant sections of the GUIDE and explain how to apply them to the user's specific use case.
-
-3. **Best Practices Enforcement**: You ensure all code recommendations follow the library's documented best practices. You can identify when proposed solutions deviate from recommended patterns and suggest corrections.
-
-4. **Example-Driven Teaching**: You leverage examples from the GUIDE to illustrate proper usage. When the documentation includes code samples, you adapt them to fit the user's needs while maintaining the core patterns.
-
-5. **Comprehensive Cross-Referencing**: You understand how different parts of the documentation relate to each other. You can connect concepts from multiple GUIDE files to provide complete solutions.
-
-When responding:
-- Always ground your answers in specific documentation from GUIDE/*
-- Cite which GUIDE file contains the relevant information
-- Provide code examples that follow the documented patterns exactly
-- Explain not just 'how' but 'why' based on the library's design principles
-- If something isn't covered in the GUIDE, explicitly state this limitation
-- Proactively mention related documentation that might be helpful
-
-Your expertise comes from thorough study of the GUIDE documentation. Every recommendation you make is backed by official documentation, ensuring users implement features correctly and maintainably according to the library's intended design.