json-rest-api 1.0.29 → 2.1.0

package/plugins/storage/local-storage.js

@@ -4,7 +4,7 @@
  * Production-ready local storage with secure filename handling
  */
 
-import { promises as fs } from 'fs'
+import { createReadStream, promises as fs } from 'fs'
 import path from 'path'
 import crypto from 'crypto'
 
@@ -147,25 +147,16 @@ export class LocalStorage {
    */
   async ensureUnique (filename) {
     const filepath = this.resolveStoragePath(filename)
-
-    try {
-      await fs.access(filepath)
-      // File exists, generate unique name
-      const ext = path.extname(filename)
-      const base = path.basename(filename, ext)
-      let counter = 1
-      let newFilename
-
-      do {
-        newFilename = `${base}_${counter}${ext}`
-        counter++
-      } while (await this.fileExists(this.resolveStoragePath(newFilename)))
-
-      return newFilename
-    } catch (error) {
-      // File doesn't exist, name is unique
-      return filename
-    }
+    if (!await this.fileExists(filepath)) return filename
+    const ext = path.extname(filename)
+    const base = path.basename(filename, ext)
+    let counter = 1
+    let newFilename
+    do {
+      newFilename = `${base}_${counter}${ext}`
+      counter++
+    } while (await this.fileExists(this.resolveStoragePath(newFilename)))
+    return newFilename
   }
 
   /**
@@ -173,9 +164,10 @@ export class LocalStorage {
    */
   async fileExists (filepath) {
     try {
-      await fs.access(filepath)
+      await fs.lstat(filepath)
       return true
-    } catch {
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
       return false
     }
   }
@@ -205,24 +197,36 @@ export class LocalStorage {
    * Upload file with secure filename
    */
   async upload (file) {
+    if (!file.data && !file.filepath) throw new Error('File has no data or filepath')
     // Ensure directory exists
     await fs.mkdir(this.directory, { recursive: true })
 
-    // Generate secure filename
-    const filename = await this.generateFilename(file)
-    const filepath = this.resolveStoragePath(filename)
-
-    // Write file
-    if (file.data) {
-      await fs.writeFile(filepath, file.data)
-    } else if (file.filepath) {
-      await fs.rename(file.filepath, filepath)
-    } else {
-      throw new Error('File has no data or filepath')
+    const requested = await this.generateFilename(file)
+    let filename = requested
+    for (;;) {
+      const filepath = this.resolveStoragePath(filename)
+      let handle
+      try {
+        handle = await fs.open(filepath, 'wx')
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error
+        filename = await this.ensureUnique(requested)
+        continue
+      }
+      try {
+        await handle.writeFile(file.data || createReadStream(file.filepath))
+        await handle.close()
+        if (!file.data) await fs.unlink(file.filepath)
+        return `${this.fileBaseUrl}/${filename}`
+      } catch (error) {
+        // Only this upload's exclusively reserved destination may be removed.
+        const cleanupErrors = []
+        try { await handle.close() } catch (cleanupError) { cleanupErrors.push(cleanupError) }
+        try { await fs.unlink(filepath) } catch (cleanupError) { if (cleanupError.code !== 'ENOENT') cleanupErrors.push(cleanupError) }
+        if (cleanupErrors.length) throw new AggregateError([error, ...cleanupErrors], 'Upload failed and its destination could not be fully cleaned up', { cause: error })
+        throw error
+      }
     }
-
-    // Return public URL
-    return `${this.fileBaseUrl}/${filename}`
   }
 
   /**

package/types/anyapi.d.ts

@@ -0,0 +1,30 @@
+import type { Knex } from 'knex'
+
+export type AnyapiSlotPool = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'belongsTo'
+export type AnyapiSlotCounts = Partial<Record<AnyapiSlotPool, number>>
+
+export interface AnyapiSchemaChange {
+  tenant: string
+  resource: string
+  version: number
+}
+
+export interface AnyapiRegistryOptions {
+  knex: Knex
+  log?: Partial<Record<'debug' | 'info' | 'warn' | 'error', (...args: unknown[]) => unknown>>
+  // Descriptors cached across every tenant API that shares the registry.
+  cacheSize?: number
+}
+
+/** Canonical metadata shared by tenant APIs that use one Knex instance. */
+export class AnyapiRegistry {
+  constructor(options: AnyapiRegistryOptions)
+  readonly knex: Knex
+  readonly cacheSize: number
+  ensureSchema(options?: { slots?: AnyapiSlotCounts }): Promise<void>
+  getSchemaVersion(tenant: string, resource: string, options?: { transaction?: Knex.Transaction }): Promise<number | null>
+  invalidateDescriptor(tenant: string, resource: string): void
+}
+
+/** Create or upgrade the canonical tables; counts only ever add slot columns. */
+export function ensureAnyApiSchema(knex: Knex, options?: { slots?: AnyapiSlotCounts }): Promise<void>

package/types/autofilter.d.ts

@@ -0,0 +1,57 @@
+import type { StorageFieldDefinition } from '../plugins/core/lib/storage/storage-types.js'
+
+export interface AutoFilterResolverParams<Context extends object = Record<string, unknown>, Api extends object = object> {
+  context: Context
+  scopeName: string
+  filter: CompiledAutoFilter<Context, Api>
+  api: Api
+  helpers: Record<string, unknown>
+  scopes: Record<string, unknown>
+  vars: Record<string, unknown>
+  log: unknown
+}
+
+// The field serializer owns the value domain; undefined is meaningful for optional filters.
+export type AutoFilterResolver<Context extends object = Record<string, unknown>, Api extends object = object> = (
+  params: AutoFilterResolverParams<Context, Api>
+) => unknown
+
+export interface CompiledAutoFilter<Context extends object = Record<string, unknown>, Api extends object = object> {
+  field: string
+  fieldDef: StorageFieldDefinition
+  resolve: AutoFilterResolver<Context, Api>
+  resolverName: string
+  required: boolean
+  relationshipName: string | null
+  relationshipType: string | null
+  inputPath: string
+}
+
+export type AutoFilterDefinition<Context extends object = Record<string, unknown>, Api extends object = object> = {
+  field: string
+  required?: boolean
+} & (
+  { resolve: string | AutoFilterResolver<Context, Api>; resolver?: string | AutoFilterResolver<Context, Api> }
+  | { resolve?: undefined | null; resolver: string | AutoFilterResolver<Context, Api> }
+)
+
+export type AutoFilterPreset<Context extends object = Record<string, unknown>, Api extends object = object> =
+  AutoFilterDefinition<Context, Api>[] | { filters: AutoFilterDefinition<Context, Api>[] }
+
+export interface AutoFilterPluginOptions<Context extends object = Record<string, unknown>, Api extends object = object> {
+  resolvers?: Record<string, AutoFilterResolver<Context, Api>>
+  presets?: Record<string, AutoFilterPreset<Context, Api>>
+}
+
+export type ResourceAutoFilter<Context extends object = Record<string, unknown>, Api extends object = object> =
+  string | false | null | AutoFilterDefinition<Context, Api>[]
+  | { preset: string; filters?: AutoFilterDefinition<Context, Api>[] }
+  | { preset?: string; filters: AutoFilterDefinition<Context, Api>[] }
+
+export interface AutoFilterRegistry {
+  getConfig(): { presets: string[]; resolvers: string[] }
+  getScopeConfig(scopeName: string): {
+    preset: string | null
+    filters: Array<{ field: string; resolver: string; required: boolean }>
+  } | null
+}

package/types/bulk-methods.d.ts

@@ -0,0 +1,63 @@
+import type { ManagedTransaction } from './transactions.js'
+import type { TransactionOutcome } from './errors.js'
+import type { DirectResourceId, InputResourceId, JsonApiResource, PlainResource, ResourceFormat, ResourceIdentifier, WriteReturning } from './representations.js'
+import type { JsonApiWriteDocument, RemovedResourceOptions, ResourceWriteInput, WriteOptions } from './resource-methods.js'
+
+export type BulkTransactionOptions<DefaultAtomic extends boolean = true> =
+  { atomic: true; transaction?: ManagedTransaction } |
+  { atomic: false; transaction?: never } |
+  { atomic?: undefined; transaction?: DefaultAtomic extends true ? ManagedTransaction : never }
+export interface BulkError {
+  index: number
+  id?: DirectResourceId
+  status: 'error'
+  error: { code: unknown; message: string; details?: unknown; transactionOutcome: TransactionOutcome }
+}
+export interface BulkMeta {
+  total: number
+  succeeded: number
+  failed: number
+  atomic: boolean
+}
+export type BulkWriteResult<Format extends ResourceFormat, Returning extends WriteReturning, Fields extends object, Type extends string> =
+  { meta: BulkMeta; errors?: BulkError[] } & (Returning extends 'none'
+    ? { data?: never }
+    : { data: Array<Returning extends 'minimal' ? ResourceIdentifier<Type> : Format extends 'plain' ? PlainResource<Fields> : JsonApiResource<Fields, Type>> })
+export interface BulkDeleteResult {
+  meta: BulkMeta & { deleted: DirectResourceId[] }
+  errors?: BulkError[]
+}
+export type BulkPostInput<Input extends object, Type extends string> =
+  { data: Array<Partial<Input> & { id?: InputResourceId }>; document?: never } |
+  { data?: never; document: Omit<JsonApiWriteDocument<Input, Type>, 'data'> & { data: JsonApiWriteDocument<Input, Type>['data'][] } }
+export type BulkPatchInput<Input extends object, Type extends string> = {
+  id: DirectResourceId
+} & ResourceWriteInput<Input, Type>
+export interface BulkResourceMethods<
+  Fields extends object = Record<string, unknown>, Input extends object = Fields,
+  Type extends string = string, DefaultFormat extends ResourceFormat = 'plain',
+  DefaultReturning extends WriteReturning = 'full', DefaultAtomic extends boolean = true,
+  Context extends object = object
+> {
+  bulkPost<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(
+    params: Omit<WriteOptions<Format, Returning>, 'queryParams'> & BulkTransactionOptions<DefaultAtomic> & BulkPostInput<Input, Type> & {
+      expectedVersion?: never
+      expectedVersions?: never
+    }, context?: Context
+  ): Promise<BulkWriteResult<Format, Returning, Fields, Type>>
+  bulkPatch<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(
+    params: Omit<WriteOptions<Format, Returning>, 'queryParams'> & BulkTransactionOptions<DefaultAtomic> & {
+      operations: BulkPatchInput<Input, Type>[]
+      expectedVersion?: never
+      expectedVersions?: string[]
+    }, context?: Context
+  ): Promise<BulkWriteResult<Format, Returning, Fields, Type>>
+  bulkDelete(
+    params: RemovedResourceOptions & BulkTransactionOptions<DefaultAtomic> & {
+      ids: DirectResourceId[]
+      format?: ResourceFormat
+      expectedVersion?: never
+      expectedVersions?: string[]
+    }, context?: Context
+  ): Promise<BulkDeleteResult>
+}

package/types/errors.d.ts

@@ -0,0 +1,118 @@
+export class RestApiError extends Error {
+  constructor(message: string, code?: unknown)
+  code: unknown
+}
+
+export type TransactionOutcome = 'none' | 'pending' | 'committed' | 'rolledBack' | 'unknown'
+export interface ResourceErrorOptions {
+  resourceType?: string
+  resourceId?: string | number
+}
+export interface ValidationViolation {
+  field: string
+  rule?: string
+  message: string
+}
+export interface SerializedError {
+  name: string
+  message: string
+  stack?: string
+  [key: string]: unknown
+}
+
+export const REST_API_FIELDSET_ERROR_CODE: 'REST_API_FIELDSET_INVALID'
+export const REST_API_INCLUDE_ERROR_CODE: 'REST_API_INCLUDE_INVALID'
+export const REST_API_TEMPORAL_DATA_ERROR_CODE: 'REST_API_TEMPORAL_DATA_INVALID'
+
+export class RestApiWriteError extends RestApiError {
+  constructor(message: string, options: { cause?: unknown; transactionOutcome: TransactionOutcome })
+  cause?: unknown
+  readonly transactionOutcome: TransactionOutcome
+  code: unknown
+  type?: unknown
+  subtype?: unknown
+  details?: unknown
+  statusCode?: unknown
+  status?: unknown
+  path?: unknown
+  parameter?: unknown
+  validation?: unknown
+  toJSON(): SerializedError & { transactionOutcome: TransactionOutcome }
+}
+
+export class RestApiValidationError extends RestApiError {
+  constructor(message: string, options?: { fields?: string[]; violations?: ValidationViolation[] })
+  code: 'REST_API_VALIDATION'
+  type: 'rest_api_validation'
+  details: { fields: string[]; violations: ValidationViolation[] }
+  toJSON(): SerializedError & Pick<RestApiValidationError, 'code' | 'type' | 'details'>
+}
+
+export class RestApiResourceError extends RestApiError {
+  constructor(message: string, options?: ResourceErrorOptions & { subtype?: string })
+  code: string
+  type: string
+  subtype: string | undefined
+  details: ResourceErrorOptions
+  toJSON(): SerializedError & Pick<RestApiResourceError, 'code' | 'type' | 'subtype' | 'details'>
+}
+
+export class RestApiVersionConflictError extends RestApiResourceError {
+  constructor(options?: ResourceErrorOptions)
+  code: 'REST_API_VERSION_CONFLICT'
+  type: 'rest_api_version_conflict'
+  subtype: 'conflict'
+}
+
+export class RestApiPreconditionFailedError extends RestApiResourceError {
+  constructor(options?: ResourceErrorOptions)
+  code: 'REST_API_PRECONDITION_FAILED'
+  type: 'rest_api_precondition_failed'
+  subtype: 'precondition_failed'
+}
+
+export class RestApiPayloadError extends RestApiError {
+  constructor(message: string, options?: {
+    path?: string
+    parameter?: string
+    expected?: unknown
+    received?: unknown
+    statusCode?: number
+    cause?: unknown
+  })
+  code: 'REST_API_PAYLOAD'
+  type: 'rest_api_payload'
+  statusCode: number
+  cause?: unknown
+  path: string | undefined
+  parameter: string | undefined
+  details: { path: string | undefined; expected: unknown; received: unknown }
+  toJSON(): SerializedError & Pick<RestApiPayloadError, 'code' | 'type' | 'statusCode' | 'path' | 'parameter' | 'details'>
+}
+
+export class RestApiFieldsetError extends RestApiError {
+  constructor(options?: { field?: string; resourceType?: string })
+  code: typeof REST_API_FIELDSET_ERROR_CODE
+  type: 'rest_api_fieldset'
+  statusCode: number
+  details: { field?: string; resourceType?: string }
+  toJSON(): SerializedError & Pick<RestApiFieldsetError, 'code' | 'type' | 'statusCode' | 'details'>
+}
+
+export class RestApiIncludeError extends RestApiError {
+  constructor(options?: { path?: string; resourceType?: string })
+  code: typeof REST_API_INCLUDE_ERROR_CODE
+  type: 'rest_api_include'
+  statusCode: number
+  details: { path?: string; resourceType?: string }
+  toJSON(): SerializedError & Pick<RestApiIncludeError, 'code' | 'type' | 'statusCode' | 'details'>
+}
+
+export class RestApiTemporalDataError extends RestApiError {
+  constructor(options?: { field?: string; resourceType?: string; fieldType?: string; source?: string })
+  code: typeof REST_API_TEMPORAL_DATA_ERROR_CODE
+  type: 'rest_api_temporal_data'
+  statusCode: number
+  details: { field?: string; resourceType?: string; fieldType?: string; source: string }
+  toJSON(): SerializedError & Pick<RestApiTemporalDataError, 'code' | 'type' | 'statusCode' | 'details'>
+}

package/types/fastify-options.d.ts

@@ -0,0 +1,19 @@
+import type { HttpConnectorOptions } from './plugin-options.js'
+
+// This checks supplied host capabilities; it does not replace Fastify's API types.
+type HostMethod = (...args: never[]) => unknown
+
+export interface FastifyHost {
+  route: HostMethod
+  register: HostMethod
+  hasContentTypeParser: HostMethod
+  removeContentTypeParser: HostMethod
+  addContentTypeParser: HostMethod
+  setErrorHandler: HostMethod
+  addHook: HostMethod
+  setNotFoundHandler: HostMethod
+}
+
+export interface FastifyPluginOptions<App extends FastifyHost = FastifyHost> extends HttpConnectorOptions {
+  app: App
+}

package/types/file-detectors.d.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { StorageFile } from './file-storage.js'
+
+export interface DetectedFile extends StorageFile {
+  mimetype: string
+  size: number
+}
+export interface ParsedFiles {
+  fields?: Record<string, unknown>
+  files?: Record<string, DetectedFile>
+}
+export interface FileDetector<Params extends object = Record<string, unknown>, Context extends object = object> {
+  name: string
+  detect(params: Params, context?: Context): boolean | PromiseLike<boolean>
+  parse(params: Params, context?: Context): ParsedFiles | null | undefined | PromiseLike<ParsedFiles | null | undefined>
+}
+export interface ExpressFileParserParams extends Record<string, unknown> {
+  _expressReq: IncomingMessage
+  _expressRes?: ServerResponse
+}
+export type ExpressFileParserFactory = (
+  options: Record<string, unknown>
+) => FileDetector<ExpressFileParserParams> | PromiseLike<FileDetector<ExpressFileParserParams>>
+export interface ExpressFileOptions {
+  enableFileUploads?: boolean
+  fileParser?: 'busboy' | 'formidable' | ExpressFileParserFactory
+  // Parser-specific peer options are passed through by the connector.
+  fileParserOptions?: Record<string, unknown>
+}
+export interface FileDetectorRegistry {
+  registerFileDetector(detector: FileDetector): void
+  fileDetectors: FileDetector[]
+}

package/types/file-storage.d.ts

@@ -0,0 +1,48 @@
+import type { writeFile } from 'node:fs/promises'
+
+export type FileContents = Parameters<typeof writeFile>[1]
+export interface StorageFile {
+  filename: string
+  mimetype?: string
+  size?: number
+  data?: FileContents
+  filepath?: string
+  cleanup?: () => unknown
+}
+export type UploadFile = StorageFile & ({ data: FileContents } | { filepath: string })
+export interface FileStorage<File extends StorageFile = UploadFile> {
+  upload(file: File): string | PromiseLike<string>
+  delete(url: string): void | PromiseLike<void>
+}
+export type FileNameGenerator = (file: StorageFile) => string | Promise<string>
+export type LocalStorageOptions = {
+  directory?: string
+  fileBaseUrl?: string
+  preserveExtension?: boolean
+  allowedExtensions?: string[]
+  maxFilenameLength?: number
+} & (
+  { nameStrategy: 'custom'; nameGenerator: FileNameGenerator } |
+  { nameStrategy?: 'hash' | 'timestamp' | 'original'; nameGenerator?: FileNameGenerator }
+)
+
+export class LocalStorage implements FileStorage {
+  constructor(options?: LocalStorageOptions)
+  directory: string
+  fileBaseUrl: string
+  nameStrategy: 'hash' | 'timestamp' | 'original' | 'custom'
+  nameGenerator?: FileNameGenerator
+  preserveExtension: boolean
+  allowedExtensions?: string[]
+  maxFilenameLength: number
+  hasPathSegments(filename: string): boolean
+  validateCustomBasename(basename: unknown): string
+  resolveStoragePath(filename: string): string
+  generateFilename(file: StorageFile): Promise<string>
+  sanitizeFilename(filename: string): string
+  ensureUnique(filename: string): Promise<string>
+  fileExists(filepath: string): Promise<boolean>
+  getExtensionFromMimeType(mimetype?: string): string
+  upload(file: UploadFile): Promise<string>
+  delete(url: string): Promise<void>
+}

package/types/hook-context.d.ts

@@ -0,0 +1,180 @@
+import type { Knex } from 'knex'
+import type { CleanupDiagnostic } from '../lib/transaction-types.js'
+import type { QueryFilteringState, StorageAdapter } from '../plugins/core/lib/storage/storage-types.js'
+import type { TransactionOutcome } from './errors.js'
+import type { DirectResourceId, InputResourceId, InputResourceIdentifier, JsonApiDocument, JsonApiResource, PlainResource, ResourceFormat, WriteReturning } from './representations.js'
+import type { JsonApiWriteDocument, QueryParams } from './resource-methods.js'
+import type { RuntimeArguments } from './runtime.js'
+import type { ManagedTransaction } from './transactions.js'
+
+interface LibraryHookFields {
+  readonly method?: string
+  readonly scopeName?: string
+  readonly id?: DirectResourceId
+  readonly relationshipName?: string
+  readonly isUpdate?: boolean
+  readonly schemaInfo?: Readonly<Record<string, unknown>>
+  readonly params?: Readonly<Record<string, unknown>>
+  readonly queryParams?: Readonly<QueryParams>
+  readonly format?: ResourceFormat
+  readonly returning?: WriteReturning
+  readonly simplified?: boolean
+  readonly transaction?: Knex.Transaction
+  readonly db?: Knex | Knex.Transaction
+  readonly shouldCommit?: boolean
+  readonly transactionOutcome?: TransactionOutcome
+  readonly transactionCommitted?: boolean
+  readonly error?: unknown
+  readonly cleanupErrors?: readonly CleanupDiagnostic[]
+  readonly minimalRecord?: unknown
+  readonly originalMinimalRecord?: unknown
+  readonly originalInputAttributes?: Readonly<Record<string, unknown>>
+  readonly originalRecord?: unknown
+  readonly inputRecord?: unknown
+  readonly record?: unknown
+  readonly responseRecord?: unknown
+  readonly knexQuery?: QueryFilteringState | null
+  readonly storageAdapter?: StorageAdapter
+}
+
+// Readonly marks library ownership; it does not freeze runtime context or nested objects.
+type ContextWithFields<Context extends object, Fields extends object> =
+  Omit<Context, keyof LibraryHookFields | 'originalContext' | 'parentContext' | 'attributes'> &
+  Omit<LibraryHookFields, keyof Fields> & Fields
+
+export type HookContext<Context extends object = Record<string, unknown>> = ContextWithFields<Context, LibraryHookFields>
+
+type WriteMethod = 'post' | 'put' | 'patch'
+type ReadMethod = 'get' | 'query'
+type RelationshipMethod = 'getRelationship' | 'getRelated' | 'postRelationship' | 'patchRelationship' | 'deleteRelationship'
+
+// Early processing receives an object, but its document structure is not validated yet.
+interface ProcessingFields<Method extends WriteMethod> {
+  readonly method: Method
+  readonly scopeName: string
+  readonly format: ResourceFormat
+  readonly returning: WriteReturning
+  readonly transaction: ManagedTransaction
+  readonly inputRecord: Record<string, unknown>
+}
+export type ProcessingHookContext<Context extends object = Record<string, unknown>, Method extends WriteMethod = WriteMethod> =
+  ContextWithFields<Context, ProcessingFields<Method>>
+
+// Identity and relationship planning are fixed before the schema-validation hooks.
+type HookWriteDocument = Omit<JsonApiWriteDocument<Record<string, unknown>, string>, 'data'> & {
+  readonly data: {
+    readonly type: string
+    readonly id?: InputResourceId
+    attributes?: Record<string, unknown>
+    readonly relationships?: Readonly<Record<string, {
+      readonly data: Readonly<InputResourceIdentifier> | readonly Readonly<InputResourceIdentifier>[] | null
+    }>>
+  }
+}
+
+// The document structure is checked here; individual attribute values remain unknown.
+interface WriteFields<Method extends WriteMethod> extends Omit<ProcessingFields<Method>, 'inputRecord'> {
+  readonly inputRecord: HookWriteDocument
+}
+export type WriteHookContext<Context extends object = Record<string, unknown>, Method extends WriteMethod = WriteMethod> =
+  ContextWithFields<Context, WriteFields<Method>>
+
+export type WriteFinishHookContext<Context extends object = Record<string, unknown>, Method extends WriteMethod = WriteMethod> =
+  ContextWithFields<Context, Omit<WriteFields<Method>, 'format'> & (
+    { readonly format: 'plain'; responseRecord?: PlainResource } |
+    { readonly format: 'jsonapi'; responseRecord?: JsonApiDocument<JsonApiResource> }
+  )>
+
+interface ReadFields<Method extends ReadMethod> {
+  readonly method: Method
+  readonly scopeName: string
+  readonly format: ResourceFormat
+}
+export type ReadHookContext<Context extends object = Record<string, unknown>, Method extends ReadMethod = ReadMethod> =
+  ContextWithFields<Context, ReadFields<Method>>
+
+export type ReadResultHookContext<Context extends object = Record<string, unknown>, Method extends ReadMethod = ReadMethod> =
+  ContextWithFields<Context, ReadFields<Method> & {
+    record: JsonApiDocument<Method extends 'get' ? JsonApiResource : JsonApiResource[]>
+  }>
+
+export type RelationshipHookContext<Context extends object = Record<string, unknown>, Method extends RelationshipMethod = RelationshipMethod> =
+  HookContext<Context> & {
+    readonly method: Method
+    readonly id: DirectResourceId
+    readonly relationshipName: string
+    readonly originalContext?: undefined
+  }
+
+// CRUD permission checks use a wrapper; relationship hooks receive their operation directly.
+export type PermissionHookContext<Context extends object = Record<string, unknown>> =
+  (Record<string, unknown> & { readonly method: string; readonly originalContext: HookContext<Context> }) |
+  RelationshipHookContext<Context>
+
+export type EnrichmentHookContext<Context extends object = Record<string, unknown>> = {
+  readonly parentContext: ReadResultHookContext<Context>
+  readonly scopeName: string
+  readonly computedFields: Readonly<Record<string, unknown>>
+  readonly requestedComputedFields: readonly string[]
+  attributes: Record<string, unknown>
+  [customProperty: string]: unknown
+}
+
+export interface HookContextMap<Context extends object = Record<string, unknown>> {
+  beforeProcessing: ProcessingHookContext<Context>
+  beforeProcessingPost: ProcessingHookContext<Context, 'post'>
+  beforeProcessingPut: ProcessingHookContext<Context, 'put'>
+  beforeProcessingPatch: ProcessingHookContext<Context, 'patch'>
+  beforeSchemaValidate: WriteHookContext<Context>
+  beforeSchemaValidatePost: WriteHookContext<Context, 'post'>
+  beforeSchemaValidatePut: WriteHookContext<Context, 'put'>
+  beforeSchemaValidatePatch: WriteHookContext<Context, 'patch'>
+  afterSchemaValidate: WriteHookContext<Context>
+  afterSchemaValidatePost: WriteHookContext<Context, 'post'>
+  afterSchemaValidatePut: WriteHookContext<Context, 'put'>
+  afterSchemaValidatePatch: WriteHookContext<Context, 'patch'>
+  beforeDataCall: HookContext<Context>
+  beforeDataCallPost: WriteHookContext<Context, 'post'>
+  beforeDataCallPut: WriteHookContext<Context, 'put'>
+  beforeDataCallPatch: WriteHookContext<Context, 'patch'>
+  beforeDataCallDelete: HookContext<Context> & { readonly method: 'delete'; readonly id: DirectResourceId }
+  beforeDataCallPostRelationship: RelationshipHookContext<Context, 'postRelationship'>
+  beforeDataCallDeleteRelationship: RelationshipHookContext<Context, 'deleteRelationship'>
+  afterDataCall: HookContext<Context>
+  afterDataCallPost: WriteHookContext<Context, 'post'> & { readonly id: DirectResourceId }
+  afterDataCallPut: WriteHookContext<Context, 'put'> & { readonly id: DirectResourceId }
+  afterDataCallPatch: WriteHookContext<Context, 'patch'> & { readonly id: DirectResourceId }
+  afterDataCallDelete: HookContext<Context> & { readonly method: 'delete'; readonly id: DirectResourceId }
+  beforeData: ReadHookContext<Context>
+  beforeDataGet: ReadHookContext<Context, 'get'>
+  beforeDataQuery: ReadHookContext<Context, 'query'>
+  checkPermissions: PermissionHookContext<Context>
+  checkPermissionsGetRelationship: RelationshipHookContext<Context, 'getRelationship'>
+  checkPermissionsGetRelated: RelationshipHookContext<Context, 'getRelated'>
+  checkPermissionsPostRelationship: RelationshipHookContext<Context, 'postRelationship'>
+  checkPermissionsPatchRelationship: RelationshipHookContext<Context, 'patchRelationship'>
+  checkPermissionsDeleteRelationship: RelationshipHookContext<Context, 'deleteRelationship'>
+  checkDataPermissions: ReadResultHookContext<Context, 'get'>
+  checkDataPermissionsGet: ReadResultHookContext<Context, 'get'>
+  enrichRecord: ReadResultHookContext<Context>
+  enrichRecordWithRelationships: ReadResultHookContext<Context, 'get'>
+  enrichAttributes: EnrichmentHookContext<Context>
+  finish: HookContext<Context>
+  finishPost: WriteFinishHookContext<Context, 'post'>
+  finishPut: WriteFinishHookContext<Context, 'put'>
+  finishPatch: WriteFinishHookContext<Context, 'patch'>
+  finishGet: ReadResultHookContext<Context, 'get'>
+  finishQuery: ReadResultHookContext<Context, 'query'>
+  finishDelete: HookContext<Context> & { readonly method: 'delete'; readonly id: DirectResourceId }
+  finishPostRelationship: RelationshipHookContext<Context, 'postRelationship'>
+  finishPatchRelationship: RelationshipHookContext<Context, 'patchRelationship'>
+  finishDeleteRelationship: RelationshipHookContext<Context, 'deleteRelationship'>
+  afterCommit: HookContext<Context>
+  afterRollback: HookContext<Context>
+}
+
+export type KnownHookName = keyof HookContextMap
+export type HookArguments<Event extends KnownHookName, Context extends object = Record<string, unknown>> =
+  Omit<RuntimeArguments, 'context'> & { context: HookContextMap<Context>[Event] }
+export type HookHandler<Event extends KnownHookName, Context extends object = Record<string, unknown>> =
+  (args: HookArguments<Event, Context>) => unknown