json-rest-api 2.0.0 → 2.2.0

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

@@ -213,7 +213,7 @@ export const validateCompleteReplacePayload = ({
     if (!fieldDef) continue
     if (fieldName === idProperty) continue
     if (Object.hasOwn(belongsToUpdates, fieldName)) continue
-    if (fieldDef.computed === true || fieldDef.virtual === true) continue
+    if (fieldDef.computed === true || fieldDef.virtual === true || fieldDef.retired === true) continue
     if (fieldDef.type === undefined) continue
 
     if (fieldDef.belongsTo && fieldDef.as) {
@@ -296,8 +296,16 @@ export const validateResourceAttributesBeforeWrite = async ({
   /** @type {StorageRow} */
   const attributesForValidation = { ...attributesToValidate }
   const foreignKeyViolations = []
+  const retiredViolations = []
   for (const [field, value] of Object.entries(attributesToValidate)) {
     const definition = schemaStructure[field]
+    if (definition?.retired === true && value !== undefined) {
+      retiredViolations.push({
+        field: `data.attributes.${field}`,
+        rule: 'retired_field',
+        message: `Field '${field}' is retired and accepts no new values`
+      })
+    }
     if (!definition?.belongsTo || !definition.as || Object.hasOwn(belongsToUpdates, field)) continue
     delete attributesForValidation[field]
     if (value === undefined) continue
@@ -307,6 +315,13 @@ export const validateResourceAttributesBeforeWrite = async ({
       message: `Foreign key field '${field}' should not be in attributes. Use 'data.relationships.${definition.as}' instead.`
     })
   }
+  const [firstRetired] = retiredViolations
+  if (firstRetired) {
+    throw new RestApiValidationError(firstRetired.message, {
+      fields: retiredViolations.map(violation => violation.field),
+      violations: retiredViolations
+    })
+  }
   if (foreignKeyViolations.length) {
     throw new RestApiValidationError('Foreign key fields cannot be set directly in attributes', {
       fields: foreignKeyViolations.map(violation => violation.field),

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

@@ -10,6 +10,7 @@ import registerRelationshipRoutes from './rest-api-plugin-hooks/register-relatio
 
 // Import method functions
 import queryMethod from './rest-api-plugin-methods/query.js'
+import aggregateMethod from './rest-api-plugin-methods/aggregate.js'
 import getMethod from './rest-api-plugin-methods/get.js'
 import postMethod from './rest-api-plugin-methods/post.js'
 import putMethod from './rest-api-plugin-methods/put.js'
@@ -90,6 +91,7 @@ export const RestApiPlugin = {
 
     // Main REST methods
     addResourceMethod('query', withAvailableContext(queryMethod))
+    addResourceMethod('aggregate', withAvailableContext(aggregateMethod))
     addResourceMethod('get', withAvailableContext(getMethod))
     addResourceMethod('post', withWriteOutcome(postMethod))
     addResourceMethod('put', withWriteOutcome(putMethod))

package/types/anyapi.d.ts

@@ -0,0 +1,32 @@
+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>
+  // Retired fields keep their slots and values and reject new writes.
+  retireFields(params: { tenant: string; resource: string; fields: string[] }, options?: { transaction?: Knex.Transaction }): Promise<Record<string, unknown>>
+  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/plugin-options.d.ts

@@ -1,6 +1,7 @@
 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
@@ -42,6 +43,17 @@ export interface RestApiKnexPluginOptions {
 }
 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

package/types/resource-methods.d.ts

@@ -23,6 +23,24 @@ export interface QueryParams extends SelectionParams {
   sort?: string[]
   page?: PageParams
 }
+export type AggregateFunction = 'count' | 'countDistinct' | 'sum' | 'avg' | 'min' | 'max'
+// One function per measure; only count accepts '*'.
+export type AggregateMeasure = { count: string } | { [Function in Exclude<AggregateFunction, 'count'>]: { [Name in Function]: string } }[Exclude<AggregateFunction, 'count'>]
+export interface AggregateParams extends TransactionParam {
+  groupBy?: string[]
+  measures: Record<string, AggregateMeasure>
+  queryParams?: {
+    filters?: Record<string, unknown>
+    // Grouped field or measure names, '-' for descending.
+    sort?: string[]
+    // Grouped results only.
+    page?: { size?: number; number?: number }
+  }
+}
+export interface AggregateResult {
+  data: Array<Record<string, unknown>>
+  meta?: { page: { size: number; number: number; hasMore: boolean } }
+}
 export interface TransactionParam {
   transaction?: Knex.Transaction
 }
@@ -78,6 +96,7 @@ export interface ResourceCoreMethods<
   query<Format extends ResourceFormat = DefaultFormat>(
     params?: RemovedResourceOptions & TransactionParam & { format?: Format; queryParams?: QueryParams }, context?: Context
   ): Promise<CollectionResult<Format, Fields, Type>>
+  aggregate(params: AggregateParams, context?: Context): Promise<AggregateResult>
   post<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(
     params: WriteOptions<Format, Returning> & ResourceWriteInput<Input, Type> & {
       expectedVersion?: never

package/types/resource-schema.d.ts

@@ -1,7 +1,7 @@
 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' |
+export type ResourceFieldType = 'string' | 'email' | 'uuid' | 'number' | 'integer' | 'boolean' | 'id' |
   'date' | 'time' | 'dateTime' | 'epochSeconds' | 'epochMilliseconds' |
   'array' | 'object' | 'file' | 'blob' | 'serialize' | 'none'
 
@@ -46,6 +46,8 @@ export interface ResourceFieldOptions {
   normallyHidden?: boolean
   virtual?: boolean
   computed?: boolean
+  // Readable and filterable, but rejects new values.
+  retired?: boolean
   include?: ResourceRelationshipOptions['include']
   search?: boolean | ResourceSearchOptions | Record<string, ResourceSearchOptions>
   dependencies?: readonly string[]
@@ -113,7 +115,7 @@ type ObjectValue<Field, Mode extends Direction> =
     : 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: 'string' | 'email' | 'uuid' | '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
@@ -147,7 +149,7 @@ type StoredNull<Field> = Field extends { required: true } | { nullable: false }
 // 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'>
+  -readonly [Key in keyof Schema as Schema[Key] extends { computed: true } | { retired: true } ? never : AttributeKey<Schema, Key>]?: FieldValue<Schema[Key], 'input'>
 }
 
 // Resource result types add optionality for sparse fields and permissions.