json-rest-api 1.0.28 → 2.0.0

package/plugins/core/rest-api-plugin-methods/get.js

@@ -1,59 +1,54 @@
+// @ts-check
+/** @import {
+ * IdentityContext, LifecycleArguments, ReadContext, Resource
+ * } from './lifecycle-types.js' */
+import { enrichIncludedAttributes } from './enrich-attributes.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
 import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
-import { getRequestedComputedFields } from '../lib/querying-writing/knex-field-helpers.js'
+import { filterResponseFields, getResourceFieldset } from '../lib/querying-writing/field-utils.js'
+import { getRequestedComputedFields, validateRequestedFieldsets } from '../lib/querying-writing/knex-field-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
-import { cascadeConfig } from './common.js'
+import { validateRequestedIncludes, filterToOneResponseLinkage } from './common.js'
 
 /**
- * GET
- * Retrieves a single resource by its type and ID.
- * @param {(string|number)} id - The unique ID of the resource to fetch.
- * @param {object} [queryParams={}] - Optional. An object to customize the query.
- * @param {string} [queryParams.include] - A comma-separated string of relationship paths to sideload (e.g., "authors,publisher").
- * @param {object} [queryParams.fields] - An object to request only specific fields (sparse fieldsets). Keys are resource types, values are comma-separated field names.
- * @returns {Promise<object>} A Promise that resolves to the JSON:API response document.
+ * Read one resource using params.id and params.queryParams. Missing resources
+ * reject; the final resource uses the selected plain or JSON:API representation.
+ * @param {LifecycleArguments<Resource>} args
  */
 export default async function getMethod ({
   params,
-  context,
+  context: callerContext,
   vars,
   helpers,
   scope,
   scopes,
   runHooks,
-  apiOptions,
-  pluginOptions,
   scopeOptions,
   scopeName,
   api
 }) {
-  context.method = 'get'
+  callerContext.method = 'get'
 
-  // Determine which simplified setting to use based on transport
-  const isTransport = params.isTransport === true
+  rejectRemovedOptions(params)
+  callerContext.format = resolveFormat(params.format, vars.format)
+  callerContext.simplified = callerContext.format === 'plain'
 
-  // Use vars which automatically cascade from scope to global
-  const defaultSimplified = isTransport ? vars.simplifiedTransport : vars.simplifiedApi
-
-  // Get simplified setting - from params only (per-call override) or use default
-  context.simplified = params.simplified !== undefined ? params.simplified : defaultSimplified
-
-  // Assign common context properties
-  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  callerContext.schemaInfo = scope.vars.schemaInfo
   const rawQueryParams = params.queryParams || {}
-  context.queryParams = {
-    fields: cascadeConfig('fields', [rawQueryParams], {}),
-    include: cascadeConfig('include', [rawQueryParams], [])
+  callerContext.queryParams = {
+    fields: rawQueryParams?.fields ?? {},
+    ...(rawQueryParams.include == null ? {} : { include: rawQueryParams.include })
   }
 
-  context.transaction = params.transaction
-  context.db = context.transaction || api.knex.instance
+  callerContext.transaction = params.transaction
+  callerContext.db = callerContext.transaction || api.knex.instance
 
-  context.scopeName = scopeName
+  callerContext.scopeName = scopeName
+  const context = /** @type {ReadContext<Resource>} */ (callerContext)
 
-  // These are just shortcuts used in this function and will be returned
   const schemaStructure = context.schemaInfo.schemaInstance.structure
   const schemaRelationships = context.schemaInfo.schemaRelationships
 
@@ -80,10 +75,12 @@ export default async function getMethod ({
   context.id = validatedRequest.id
   context.queryParams = validatedRequest.queryParams || {}
 
+  const identityContext = /** @type {IdentityContext} */ (context)
+
   // Fetch minimal record for authorization checks
   const minimalRecord = await helpers.dataGetMinimal({
     scopeName,
-    context,
+    context: identityContext,
     runHooks
   })
 
@@ -100,23 +97,22 @@ export default async function getMethod ({
 
   context.minimalRecord = minimalRecord
 
-  // Centralised checkPermissions function
   await scope.checkPermissions({
     method: 'get',
     originalContext: context,
   })
 
+  await validateRequestedFieldsets(context, scopes)
+  validateRequestedIncludes(context, scopes)
   await runHooks('beforeData')
   await runHooks('beforeDataGet')
 
   context.record = await helpers.dataGet({
     scopeName,
-    context,
+    context: identityContext,
     runHooks
   })
 
-  // Check if record was found - storage layer returns null/undefined for non-existent records.
-  // This generates a proper 404 error with JSON:API error format instead of returning empty data.
   if (!context.record || !context.record.data) {
     throw new RestApiResourceError(
       'Resource not found',
@@ -128,73 +124,46 @@ export default async function getMethod ({
     )
   }
 
-  // Normalize database values (e.g., convert 1/0 to true/false for booleans)
   context.record = normalizeRecordAttributes(context.record, scopes)
 
   await runHooks('checkDataPermissions')
   await runHooks('checkDataPermissionsGet')
 
-  // Make a backup
   context.originalRecord = structuredClone(context.record)
 
-  // This will enhance record, which is the WHOLE JSON:API record
   await runHooks('enrichRecord')
 
-  // Get computed field information for main resource
   const computedFields = scope.vars.schemaInfo?.computed || {}
-  const requestedFields = context.queryParams.fields?.[scopeName]
+  const requestedFields = getResourceFieldset(context.queryParams.fields, scopeName)
   const requestedComputedFields = getRequestedComputedFields(scopeName, requestedFields, computedFields)
 
-  // Enrich attributes for the main resource
-  // Pass computedDependencies from context (set by dataGet in Knex plugin)
-  // This tells enrichAttributes which fields to remove after computation
   context.record.data.attributes = await scope.enrichAttributes({
+    id: context.record.data.id,
     attributes: context.record.data.attributes,
     parentContext: context,
     requestedComputedFields,
     isMainResource: true,
-    computedDependencies: context.computedDependencies  // Fields to remove if not requested
+    computedDependencies: context.computedDependencies
   })
 
-  for (const entry of (context.record.included || [])) {
-    const entryScope = scopes[entry.type]
-    const entryComputed = entryScope.vars.schemaInfo?.computed || {}
-    const entryRequestedFields = context.queryParams.fields?.[entry.type]
-    const entryRequestedComputed = getRequestedComputedFields(
-      entry.type,
-      entryRequestedFields,
-      entryComputed
-    )
-
-    entry.attributes = await entryScope.enrichAttributes({
-      attributes: entry.attributes,
-      parentContext: context,
-      requestedComputedFields: entryRequestedComputed,
-      isMainResource: false,
-      computedDependencies: entry.__$jsonrestapi_computed_deps$__
-    })
-  }
+  await enrichIncludedAttributes(context, scopes)
 
   await runHooks('enrichRecordWithRelationships')
 
-  // The called hooks should NOT change context.record
   await runHooks('finish')
   await runHooks('finishGet')
+  await filterToOneResponseLinkage(context, scopes)
 
   // Enrichers and finish hooks run after the database pass and may introduce
   // native values. Reassert the public temporal contract at the return boundary.
   context.record = normalizeRecordAttributes(context.record, scopes, {
     source: 'response'
   })
+  filterResponseFields(context.record, context.queryParams.fields)
 
-  // Get schema info for transformation
-  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  context.schemaInfo = scope.vars.schemaInfo
 
-  // Transform output if in simplified mode
   if (context.simplified) {
-    // Convert JSON:API response back to simplified format
-    // Example: {data: {type: 'posts', id: '1', attributes: {title: 'My Post'}, relationships: {author: {data: {type: 'users', id: '123'}}}}}
-    // becomes: {id: '1', title: 'My Post', author_id: '123'} - flattens structure and restores foreign keys
     return transformJsonApiToSimplified(
       { record: context.record },
       { context: { schemaStructure, schemaRelationships, scopes } }

package/plugins/core/rest-api-plugin-methods/lifecycle-types.d.ts

@@ -0,0 +1,225 @@
+import type { TransactionContext, TransactionFactory, OwnedTransaction } from '../../../lib/transaction-types.js'
+import type { ResourceFormat, WriteReturning, JsonApiDocument, JsonApiResource, ResourceIdentifier } from '../../../types/representations.js'
+import type { RestApiPluginOptions } from '../../../types/plugin-options.js'
+import type { RuntimeLogger } from '../../../types/runtime.js'
+import type { QueryParams } from '../../../types/resource-methods.js'
+import type {
+  StorageDatabase, StorageSchemaInfo, StorageFieldDefinition, StorageRow, QueryFilteringState,
+  DataWriteHelpers, CanonicalDataReadHelpers, DataRelatedIdsQuery, CanonicalLinkHelpers, QueryBuilderResult
+} from '../lib/storage/storage-types.js'
+import type { MandatoryQueryConstraint } from '../lib/querying/query-constraint.js'
+import { queryConstraint } from '../lib/querying/query-constraint.js'
+import { writePrecondition } from './common.js'
+
+export type Identifier = ResourceIdentifier
+export type RelationshipData = Identifier | Identifier[] | null
+export interface Relationship { data?: RelationshipData }
+export interface InputDocument {
+  data: {
+    type?: string
+    id?: string | number
+    attributes?: StorageRow
+    relationships?: Record<string, Relationship>
+  }
+}
+export interface Resource extends JsonApiResource { __$jsonrestapi_computed_deps$__?: string[] }
+export type Document<Data = Resource | Resource[] | null> = Omit<JsonApiDocument<Data>, 'included'> & { included?: Resource[] }
+export interface Field extends StorageFieldDefinition {
+  compute?: (args: {
+    id?: string | number
+    attributes: StorageRow
+    record: StorageRow
+    context?: LifecycleContext
+    helpers: LifecycleHelpers
+    api: LifecycleApi
+  }) => unknown
+  belongsToPolymorphic?: { typeField: string; idField: string; types: string[] }
+  through?: string
+  foreignKey?: string
+  otherKey?: string
+  target?: string
+  via?: string
+}
+export interface Schema {
+  structure: Record<string, Field>
+  create(attributes: StorageRow): Promise<ValidationResult>
+  patch(attributes: StorageRow): Promise<ValidationResult>
+  replace(attributes: StorageRow): Promise<ValidationResult>
+}
+export interface ValidationResult {
+  validatedObject: StorageRow & { id?: string | number }
+  errors: Record<string, { code?: string; message: string }>
+}
+export interface FieldCallbackContext {
+  id?: string | number
+  attributes: StorageRow
+  fieldName: string
+  originalValue: unknown
+  originalAttributes: StorageRow
+  record?: StorageRow
+  parentContext?: LifecycleContext
+  scopeName: string
+  method?: string
+  api: LifecycleApi
+  helpers: LifecycleHelpers
+  auth?: unknown
+  isMainResource?: boolean
+}
+export interface LifecycleSchema extends StorageSchemaInfo {
+  idProperty: string
+  readDependencies?: Record<string, readonly string[]>
+  schemaInstance: Schema
+  schemaStructure: Record<string, Field>
+  schemaRelationships: Record<string, Field>
+  outputRelationships: Record<string, Field>
+  outputFields: Record<string, Field>
+  computed: Record<string, Field>
+  foreignKeyFields: Set<string>
+  fieldSetters: Record<string, {
+    setter(value: unknown, context: FieldCallbackContext): unknown
+    runSetterAfter?: string[]
+  }>
+  fieldGetters: Record<string, { getter(value: unknown, context: FieldCallbackContext): unknown }>
+  sortedSetterFields: string[]
+  sortedGetterFields: string[]
+  sortedComputedFields: string[]
+}
+
+// Library-owned mutable working state, populated by each method before its stage runs.
+// Attribute values stay unknown until a schema or user callback interprets them.
+export interface LifecycleContext<Data = Resource | Resource[] | null, Input = InputDocument> extends TransactionContext {
+  method?: string
+  scopeName?: string
+  schemaInfo?: LifecycleSchema
+  db?: StorageDatabase
+  inputRecord?: Input
+  record?: Document<Data> | Record<string, never> | null
+  queryParams?: QueryParams
+  params?: LifecycleParams
+  id?: string | number
+  relationshipName?: string
+  format?: ResourceFormat
+  simplified?: boolean
+  returning?: WriteReturning
+  minimalRecord?: (Omit<Resource, 'id'> & { id?: string }) | null
+  originalMinimalRecord?: Omit<Resource, 'id'> & { id?: string }
+  originalInputAttributes?: StorageRow
+  originalRecord?: Document
+  responseRecord?: Document | StorageRow
+  isCreate?: boolean
+  isUpdate?: boolean
+  exists?: boolean
+  computedDependencies?: string[]
+  returnMeta?: Record<string, unknown>
+  sortableFields?: string[]
+  auth?: unknown
+  [customProperty: string]: unknown
+  knexQuery?: QueryFilteringState | null
+  [queryConstraint]?: MandatoryQueryConstraint
+}
+export interface LifecycleParams extends Record<string, unknown> {
+  id?: unknown
+  data?: StorageRow
+  document?: InputDocument
+  format?: ResourceFormat
+  returning?: WriteReturning
+  transaction?: OwnedTransaction
+  queryParams?: QueryParams
+  expectedVersion?: unknown
+  relationshipName?: string
+  relationshipData?: RelationshipData
+  [queryConstraint]?: MandatoryQueryConstraint
+  [writePrecondition]?: () => unknown
+}
+export interface LifecycleVars extends RestApiPluginOptions {
+  schemaInfo: LifecycleSchema
+  defaultSort?: string | string[]
+  sortableFields?: string[]
+}
+export interface LifecycleResource {
+  scopeOptions: RestApiPluginOptions
+  vars: LifecycleVars
+  get(params: { id?: string | number; queryParams?: QueryParams; transaction?: OwnedTransaction; format: 'jsonapi' }, context?: LifecycleContext): Promise<Document<Resource>>
+  get(params: { id?: string | number; queryParams?: QueryParams; transaction?: OwnedTransaction; format: ResourceFormat }, context?: LifecycleContext): Promise<Document<Resource> | StorageRow>
+  query(params: { queryParams?: QueryParams; transaction?: OwnedTransaction; format: 'jsonapi'; [queryConstraint]?: MandatoryQueryConstraint }, context?: LifecycleContext): Promise<Document<Resource[]>>
+  patch(params: { id?: string | number; document: InputDocument; transaction?: OwnedTransaction; expectedVersion?: unknown; format: 'jsonapi'; returning: 'none' }, context?: LifecycleContext): Promise<void>
+  checkPermissions(params: { method: string; originalContext: LifecycleContext }): Promise<unknown>
+  applyQueryFilters(params: QueryFilteringState, context: LifecycleContext): Promise<{ query: QueryBuilderResult } | null | undefined>
+  enrichAttributes(params: EnrichmentParams): Promise<StorageRow>
+}
+export interface LifecycleApi {
+  resources: Record<string, LifecycleResource>
+  knex: { instance: StorageDatabase }
+  anyapi?: { links?: CanonicalLinkHelpers }
+}
+export interface LifecycleHelpers extends DataWriteHelpers<unknown, unknown>, CanonicalDataReadHelpers {
+  newTransaction: TransactionFactory
+  db: StorageDatabase
+  dataRelatedIdsQuery: DataRelatedIdsQuery
+}
+export type RunHooks = (event: string) => Promise<unknown>
+export interface LifecycleArguments<Data = Resource | Resource[] | null> {
+  params: LifecycleParams
+  context: LifecycleContext<Data>
+  vars: LifecycleVars
+  helpers: LifecycleHelpers
+  scope: LifecycleResource
+  scopes: Record<string, LifecycleResource>
+  runHooks: RunHooks
+  scopeOptions: RestApiPluginOptions
+  scopeName: string
+  api: LifecycleApi
+  log: RuntimeLogger
+}
+export interface EnrichmentParams {
+  id?: string | number
+  attributes?: StorageRow
+  parentContext?: LifecycleContext
+  requestedComputedFields?: string[]
+  isMainResource?: boolean
+  computedDependencies?: string[]
+}
+export interface EnrichmentArguments extends Omit<LifecycleArguments, 'params' | 'context'> {
+  params: EnrichmentParams
+  context: Record<string, unknown> & { attributes?: StorageRow }
+}
+
+export interface RelationshipPlan {
+  belongsToUpdates: StorageRow
+  belongsToTargets: Identifier[]
+  manyToManyRelationships: Array<{ relName: string; relDef: PivotField; relData: Identifier[] }>
+  reverseRelationships: Array<{ relName: string; relDef: Field; relData: RelationshipData }>
+}
+
+// These are type views of the same object after the named stage establishes its fields.
+export type ResourceContext<Input = InputDocument> = LifecycleContext<Resource | Resource[] | null, Input> & {
+  method: string
+  scopeName: string
+  schemaInfo: LifecycleSchema
+  db: StorageDatabase
+}
+export type IdentityContext = ResourceContext & { id: string | number }
+export type RelationshipContext = IdentityContext & { id: string; relationshipName: string }
+export type WriteRelationshipContext = RelationshipContext & { transaction: OwnedTransaction }
+export type ReadContext<Data = Resource | Resource[] | null> = ResourceContext & {
+  format: ResourceFormat
+  simplified: boolean
+  queryParams: QueryParams
+  record?: Document<Data> | null
+}
+export type QueryContext = ReadContext<Resource[]> & { queryParams: QueryParams & { sort: string[] } }
+export type ProcessingContext = ResourceContext<unknown> & {
+  inputRecord: object
+  params: LifecycleParams
+  queryParams: QueryParams
+  format: ResourceFormat
+  simplified: boolean
+  returning: WriteReturning
+  transaction: OwnedTransaction
+}
+export type WriteContext = ProcessingContext & { inputRecord: InputDocument }
+export type CompletedWriteContext = WriteContext & { id: string | number }
+export type PivotField = Field & { through: string; foreignKey: string; otherKey: string }
+
+export type RelationshipArguments = LifecycleArguments & { params: LifecycleParams & { relationshipName: string } }
+export type RelationshipWriteArguments<Data = RelationshipData> = RelationshipArguments & { params: LifecycleParams & { relationshipData: Data } }

package/plugins/core/rest-api-plugin-methods/patch-relationship.js

@@ -1,3 +1,9 @@
+// @ts-check
+/** @import {
+ * RelationshipWriteArguments, WriteRelationshipContext
+ * } from './lifecycle-types.js' */
+import { beginWriteTransaction } from '../../../lib/error-context.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
 import {
   commitOwnedTransaction,
   handleWriteMethodError,
@@ -6,30 +12,28 @@ import {
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 
 /**
- * PATCH RELATIONSHIP
- * Completely replaces a relationship
- * PATCH /api/articles/1/relationships/author
- *
- * @param {string} id - The ID of the resource
- * @param {string} relationshipName - The name of the relationship
- * @param {object|array} relationshipData - New relationship data
- * @returns {Promise<void>} 204 No Content
+ * Replace the selected relationship with params.relationshipData.
+ * Validate relationship permission/cardinality, then delegate the data mutation
+ * and version handling to PATCH using the same transaction. This outer method
+ * runs its own finish hooks and completes the transaction only when it owns it.
+ * @param {RelationshipWriteArguments} args
  */
-export default async function patchRelationshipMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeOptions, scopeName, api, log }) {
-  context.method = 'patchRelationship'
-  context.id = requireExistingResourceId(params.id, {
+export default async function patchRelationshipMethod ({ params, context: callerContext, vars, helpers, scope, scopes, runHooks, scopeOptions, scopeName, api, log }) {
+  rejectRemovedOptions(params)
+  if (params.format !== undefined) resolveFormat(params.format)
+  callerContext.method = 'patchRelationship'
+  callerContext.scopeName = scopeName
+  callerContext.id = requireExistingResourceId(params.id, {
     scopeOptions,
     vars,
     scopeName
   })
-  context.relationshipName = params.relationshipName
-  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  callerContext.relationshipName = params.relationshipName
+  callerContext.schemaInfo = scope.vars.schemaInfo
 
-  // Transaction handling
-  context.transaction = params.transaction ||
-    (helpers.newTransaction && !params.transaction ? await helpers.newTransaction() : null)
-  context.shouldCommit = !params.transaction && !!context.transaction
-  context.db = context.transaction || api.knex.instance
+  await beginWriteTransaction(callerContext, params.transaction, helpers.newTransaction, runHooks)
+  callerContext.db = callerContext.transaction || api.knex.instance
+  const context = /** @type {WriteRelationshipContext} */ (callerContext)
 
   try {
     // Check permissions
@@ -47,7 +51,7 @@ export default async function patchRelationshipMethod ({ params, context, vars,
     // Reuse existing patch with relationship data
     await scope.patch({
       id: context.id,
-      inputRecord: {
+      document: {
         data: {
           type: scopeName,
           id: context.id,
@@ -57,17 +61,16 @@ export default async function patchRelationshipMethod ({ params, context, vars,
         }
       },
       transaction: context.transaction,
-      simplified: false,
-      isTransport: params.isTransport
+      expectedVersion: params.expectedVersion,
+      format: 'jsonapi',
+      returning: 'none',
     }, { ...context })
 
     await runHooks('finish')
     await runHooks('finishPatchRelationship')
 
-    await commitOwnedTransaction(context, runHooks)
-
-    // 204 No Content
+    await commitOwnedTransaction(context)
   } catch (error) {
-    await handleWriteMethodError(error, context, 'PATCH_RELATIONSHIP', scopeName, log, runHooks)
+    await handleWriteMethodError(error, context, 'PATCH_RELATIONSHIP', scopeName, log)
   }
 }