json-rest-api 2.1.0 → 2.3.0

package/plugins/core/lib/querying-writing/default-data-helpers.js

@@ -24,6 +24,10 @@ export const defaultDataHelpers = {
     throw new Error('No storage implementation for query. Install a storage plugin.')
   },
 
+  dataAggregate: async function (request) {
+    throw new Error('No storage implementation for aggregate. Install a storage plugin.')
+  },
+
   dataPost: async function (request) {
     throw new Error('No storage implementation for post. Install a storage plugin.')
   },

package/plugins/core/lib/querying-writing/field-types.js

@@ -0,0 +1,43 @@
+import { addType } from 'json-rest-schema'
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const UUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
+const TEXT_SEARCH_OPERATORS = new Set(['like', 'contains', 'startswith', 'endswith'])
+
+// Partial-match filters search fragments of a value, not whole values.
+const isTextSearch = definition => TEXT_SEARCH_OPERATORS.has(String(definition?.filterOperator).toLowerCase())
+
+const formattedStringType = (pattern, format) => {
+  const type = (context) => {
+    if (typeof context.value !== 'string') context.throwTypeError()
+    const value = context.definition.noTrim ? context.value : context.value.trim()
+    if (!isTextSearch(context.definition) && !pattern.test(value)) context.throwTypeError()
+    return value
+  }
+  type.toJsonSchema = ({ definition }) => isTextSearch(definition) ? { type: 'string' } : { type: 'string', format, pattern: pattern.source }
+  return type
+}
+
+let installed = false
+
+/** Register the string types json-rest-schema lacks; both storages keep them in string columns. */
+export function installFieldTypes () {
+  if (installed) return
+  installed = true
+  addType('email', formattedStringType(EMAIL_PATTERN, 'email'))
+  addType('uuid', formattedStringType(UUID_PATTERN, 'uuid'))
+}
+
+/**
+ * Reject field types no casting function exists for, at registration rather than on the first write.
+ * @param {{ structure: Record<string, any>, types: Record<string, unknown> }} schema
+ * @param {string} label
+ */
+export function assertKnownFieldTypes (schema, label) {
+  for (const [fieldName, definition] of Object.entries(schema.structure)) {
+    const type = definition?.type
+    if (typeof type === 'string' && !Object.hasOwn(schema.types, type)) {
+      throw new Error(`Field '${fieldName}' in ${label} has unknown type '${type}'`)
+    }
+  }
+}

package/plugins/core/lib/querying-writing/request-contracts.js

@@ -354,7 +354,7 @@ function buildWritableAttributesStructure (schemaInfo = {}) {
     if (!fieldDef) continue
     if (fieldName === idProperty) continue
     if (excludedFieldNames.has(fieldName)) continue
-    if (fieldDef.computed === true) continue
+    if (fieldDef.computed === true || fieldDef.retired === true) continue
     if (fieldDef.type === undefined) continue
     attributesStructure[fieldName] = { ...fieldDef }
   }

package/plugins/core/lib/storage/canonical-data-helpers.js

@@ -5,6 +5,7 @@ import { applySortDescriptorOrder, buildEffectiveSortList, parseSortEntry, resol
 import { normalizeId, resolveFieldInfo } from '../anyapi/utils/descriptor-helpers.js'
 import { decorateResourceLinks, getAllowedQueryFieldNames } from '../anyapi/canonical-relationship-reader.js'
 import { applyQueryConstraint } from '../querying/query-constraint.js'
+import { runAggregateQuery } from '../querying/aggregate-query.js'
 import { calculatePaginationMeta, generatePaginationLinks, generateCursorPaginationLinks, buildCursorMeta, applyPaginationToQuery } from '../querying/knex-pagination-helpers.js'
 import { getUrlPrefix, buildJsonApiLink } from '../querying/url-helpers.js'
 import { applyFieldSelectionToQuery, buildFieldSelection } from '../querying-writing/knex-field-helpers.js'
@@ -670,6 +671,33 @@ export function createCanonicalDataHelpers ({
     return response
   }
 
+  /** @type {CanonicalDataReadHelpers['dataAggregate']} */
+  const dataAggregate = async ({ scopeName, context, runHooks, plan }) => {
+    const storageAdapter = getScopeStorageAdapter(scopeName)
+    if (!storageAdapter) throw new Error(`Storage adapter for resource '${scopeName}' not found`)
+    context.storageAdapter = storageAdapter
+    const descriptor = getDescriptor(scopeName)
+    const db = context.db || context.transaction || api.knex.instance
+    const tableAlias = context.schemaInfo.tableName || descriptor.resource
+
+    const filteredState = await withQueryFilteringContext(context, {
+      query: storageAdapter.buildBaseQuery({ transaction: db, tableAlias }),
+      filters: context.queryParams.filters,
+      schemaInfo: context.schemaInfo,
+      scopeName,
+      tableName: tableAlias,
+      db,
+      queryPurpose: 'aggregate',
+      isAnyApi: true,
+      adapter: storageAdapter,
+      storageAdapter,
+    }, async () => {
+      await applyBuiltInAnyApiQueryFilters(context)
+      await runHooks('knexQueryFiltering')
+    })
+    return runAggregateQuery({ source: filteredState.query, sourceTable: tableAlias, storageAdapter, db, plan })
+  }
+
   return {
     dataExists,
     dataPost,
@@ -678,6 +706,7 @@ export function createCanonicalDataHelpers ({
     dataDelete,
     dataGet,
     dataQuery,
+    dataAggregate,
     dataGetMinimal
   }
 }

package/plugins/core/lib/storage/canonical-storage-mapping.js

@@ -1,6 +1,8 @@
 // @ts-check
 import { serializeFieldValueForStorage } from './storage-mapping.js'
 import { getPolymorphicLinkage } from '../querying-writing/relationship-contracts.js'
+import { INDEXED_STRING_LENGTH } from '../anyapi/schema-utils.js'
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
 
 /** @import { CanonicalDescriptor, StorageRow, StorageSchemaInfo, StorageWriteOptions } from './storage-types.js' */
 
@@ -34,6 +36,15 @@ export const translateCanonicalAttributesForStorage = (attributes = {}, descript
         textStorage: slot.slotType === 'string'
       })
       row[slot.slot] = definition?.type === 'id' && serialized != null ? String(serialized) : serialized
+      const stored = row[slot.slot]
+      // Databases count code points; one surrogate pair is one character.
+      if (slot.indexed && typeof stored === 'string' && stored.length > INDEXED_STRING_LENGTH && [...stored].length > INDEXED_STRING_LENGTH) {
+        const field = `data.attributes.${fieldName}`
+        throw new RestApiValidationError(`Field '${fieldName}' holds at most ${INDEXED_STRING_LENGTH} characters in its indexed slot.`, {
+          fields: [field],
+          violations: [{ field, rule: 'storage_range', message: `Indexed string slots hold at most ${INDEXED_STRING_LENGTH} characters.` }]
+        })
+      }
     }
 
     if (slot.slotType === 'belongsTo') {

package/plugins/core/lib/storage/ordinary-data-helpers.js

@@ -9,6 +9,7 @@ import { toJsonApiRecordWithBelongsTo } from '../querying-writing/knex-json-api-
 import { processIncludes } from '../querying/knex-process-includes.js'
 import { loadRelationshipIdentifiers } from '../querying/relationship-identifiers.js'
 import { applyQueryConstraint } from '../querying/query-constraint.js'
+import { runAggregateQuery } from '../querying/aggregate-query.js'
 import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
 import { getOperationDiagnosticContext } from '../../../../lib/error-context.js'
 import { applyInsertReturning } from '../querying-writing/database-capabilities.js'
@@ -505,6 +506,29 @@ export function createOrdinaryDataHelpers ({ api, scopes, knex, log, getScopeSto
     return buildJsonApiResponse(scope, records, included, false, scopeName, context)
   }
 
+  /** @type {OrdinaryDataReadHelpers['dataAggregate']} */
+  const dataAggregate = async ({ scopeName, context, runHooks, plan }) => {
+    const storageAdapter = getScopeStorageAdapter(scopeName)
+    context.storageAdapter = storageAdapter
+    const tableName = storageAdapter.getTableName()
+    const db = context.db || api.knex.instance
+
+    const filteredState = await withQueryFilteringContext(context, {
+      query: db(tableName),
+      filters: context.queryParams.filters,
+      schemaInfo: context.schemaInfo,
+      scopeName,
+      tableName,
+      db,
+      queryPurpose: 'aggregate',
+      adapter: storageAdapter,
+      storageAdapter,
+    }, async () => {
+      await runHooks('knexQueryFiltering')
+    })
+    return runAggregateQuery({ source: filteredState.query, sourceTable: tableName, storageAdapter, db, plan })
+  }
+
   /** @type {OrdinaryDataWriteHelpers['dataPost']} */
   const dataPost = async ({ scopeName, context }) => {
     const storageAdapter = getScopeStorageAdapter(scopeName)
@@ -701,6 +725,7 @@ export function createOrdinaryDataHelpers ({ api, scopes, knex, log, getScopeSto
     dataExists,
     dataGet,
     dataQuery,
+    dataAggregate,
     dataPost,
     dataPut,
     dataPatch,

package/plugins/core/lib/storage/storage-types.d.ts

@@ -79,6 +79,8 @@ export interface StorageInfo {
 export interface CanonicalFieldSlot {
   slot: string
   slotType: string
+  // The slot has a (tenant_id, resource, slot) index; belongsTo slots always do.
+  indexed?: boolean
   alias?: string
 }
 
@@ -307,6 +309,27 @@ export interface DataReadHelpers<GetResult> {
       queryParams: NonNullable<DataReadContext['queryParams']>
     }
   }) => Promise<DataDocument<DataResource[]>>
+  // The plan comes from compileAggregateRequest; filters are in context.queryParams.
+  dataAggregate: (request: DataReadRequest & {
+    runHooks: NonNullable<DataReadRequest['runHooks']>
+    context: DataReadContext & {
+      queryParams: NonNullable<DataReadContext['queryParams']>
+    }
+    plan: AggregatePlan
+  }) => Promise<AggregateResult>
+}
+
+// Compiled by compileAggregateRequest: outputs carry SQL aliases.
+export interface AggregatePlan {
+  scopeName: string
+  groups: Array<{ name: string; field: string; definition: StorageFieldDefinition; alias: string }>
+  measures: Array<{ name: string; fn: 'count' | 'countDistinct' | 'sum' | 'avg' | 'min' | 'max'; field: string; definition: StorageFieldDefinition | null; alias: string }>
+  sort: Array<{ alias: string; direction: 'asc' | 'desc' }>
+  page: { size: number; number: number } | null
+}
+export interface AggregateResult {
+  data: Array<Record<string, unknown>>
+  meta?: { page: { size: number; number: number; hasMore: boolean } }
 }
 
 export type OrdinaryDataReadHelpers = DataReadHelpers<DataDocument<DataResource>>

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

@@ -6,18 +6,25 @@ import { createEnhancedLogger } from '../../lib/enhanced-logger.js'
 import { ensureAnyApiSchema } from './lib/anyapi/schema-utils.js'
 import { AnyapiRegistry } from './lib/anyapi/anyapi-registry.js'
 import { composeResourceOptions, relatedResources } from './lib/anyapi/stored-definition.js'
-import { RestApiResourceError } from '../../lib/rest-api-errors.js'
+import { RestApiResourceError, RestApiValidationError } from '../../lib/rest-api-errors.js'
 import { compileSchemas } from './lib/querying-writing/compile-schemas.js'
 import { snapshotResourceConfiguration } from './lib/querying-writing/schema-helpers.js'
 import { assertFieldNameMap } from './lib/querying-writing/field-utils.js'
 import { polymorphicFiltersHook, crossTableFiltersHook, basicFiltersHook } from './lib/querying/knex-query-helpers.js'
 import { createStorageAdapterLookup } from './lib/storage/storage-adapter.js'
+import { translateCanonicalAttributesForStorage } from './lib/storage/canonical-storage-mapping.js'
+import { applyDatabaseReadOptions, normalizeStoredFieldValue } from './lib/querying-writing/database-value-normalizers.js'
 
 const DEFAULT_TENANT = 'default'
+const MIGRATION_BATCH_SIZE = 500
 // Methods that read a published schema; schema checks wrap these.
-const REQUEST_METHODS = ['query', 'get', 'post', 'put', 'patch', 'delete', 'getRelated', 'getRelationship', 'postRelationship', 'patchRelationship', 'deleteRelationship']
+const REQUEST_METHODS = ['query', 'aggregate', 'get', 'post', 'put', 'patch', 'delete', 'getRelated', 'getRelationship', 'postRelationship', 'patchRelationship', 'deleteRelationship']
 
-const optionsSignature = options => JSON.stringify([Object.keys(options.schema || {}).sort(), Object.keys(options.searchSchema || {}).sort()])
+const optionsSignature = options => JSON.stringify([
+  Object.keys(options.schema || {}).sort(),
+  Object.keys(options.searchSchema || {}).sort(),
+  Object.entries(options.schema || {}).filter(([, definition]) => definition?.retired === true).map(([name]) => name).sort()
+])
 
 // A validation failure may come from a schema another server already changed.
 // Writes that may have committed are never repeated.
@@ -32,7 +39,7 @@ export const RestApiAnyapiKnexPlugin = {
     const options = pluginOptions || {}
     const knex = options.knex
     const tenantId = options.tenantId || DEFAULT_TENANT
-    const { ensureSchema = true, ownsKnex = true, onSchemaChanged, schemaCheckInterval, slots } = options
+    const { ensureSchema = true, ownsKnex = true, onSchemaChanged, schemaCheckInterval, slots, indexedSlots } = options
 
     if (!knex) {
       throw new Error('AnyapiKnexPlugin requires a knex instance')
@@ -48,7 +55,7 @@ export const RestApiAnyapiKnexPlugin = {
     }
 
     const registry = options.registry || new AnyapiRegistry({ knex, log })
-    if (ensureSchema) await registry.ensureSchema({ slots })
+    if (ensureSchema) await registry.ensureSchema({ slots, indexedSlots })
 
     api.anyapi = api.anyapi || {}
     api.anyapi.registry = registry
@@ -127,6 +134,15 @@ export const RestApiAnyapiKnexPlugin = {
           tenant: tenantId, scopeName, fields: hidden, filters: hiddenFilters
         })
       }
+      // Fields never move on their own; migrateField copies one into an indexed slot.
+      const unindexed = Object.entries(scopeOptions.schema || {})
+        .filter(([name, definition]) => definition?.indexed === true && descriptor.fields[name]?.indexed === false)
+        .map(([name]) => name)
+      if (unindexed.length) {
+        await log.warn(`AnyAPI resource '${scopeName}' declares indexed fields stored in unindexed slots`, {
+          tenant: tenantId, scopeName, fields: unindexed
+        })
+      }
       const signature = optionsSignature(scopeOptions)
       let schemaInfo = scope.vars.schemaInfo
       if (compiled?.signature === signature) schemaInfo = compiled.schemaInfo
@@ -252,6 +268,7 @@ export const RestApiAnyapiKnexPlugin = {
       for (const { resource } of await registry.listResources(tenantId)) await loadResource(resource)
       return api.resources
     }
+    api.anyapi.getSchemaVersion = resource => registry.getSchemaVersion(tenantId, resource)
     api.anyapi.handleSchemaChange = async ({ tenant, resource, version } = {}) => {
       if ((tenant !== undefined && tenant !== tenantId) || typeof resource !== 'string' || !Object.hasOwn(api.resources, resource)) return false
       if (version !== undefined && publishedVersion(resource) >= version) return false
@@ -322,7 +339,7 @@ export const RestApiAnyapiKnexPlugin = {
     })
 
     addResourceMethod('createKnexTable', async ({ scopeName }) => {
-      if (ensureSchema) await ensureAnyApiSchema(knex, { slots })
+      if (ensureSchema) await ensureAnyApiSchema(knex, { slots, indexedSlots })
       const descriptor = await registry.getDescriptor(tenantId, scopeName)
       if (!descriptor) throw new Error(`Descriptor not found for resource '${scopeName}'`)
       await publish(scopeName, descriptor)
@@ -330,49 +347,141 @@ export const RestApiAnyapiKnexPlugin = {
 
     addResourceMethod('reloadSchema', async ({ scopeName }) => reload(scopeName))
 
-    addResourceMethod('addKnexFields', async ({ scopeName, params }) => {
-      if (!params?.fields || typeof params.fields !== 'object' || Array.isArray(params.fields)) {
-        throw new Error('fields parameter is required for addKnexFields')
-      }
-      assertFieldNameMap(params.fields, `added fields in '${scopeName}'`)
-      assertFieldNameMap(params.searchSchema, `added search schema in '${scopeName}'`)
-      assertFieldNameMap(params.canonicalFieldsMap, `added canonical fields in '${scopeName}'`)
-      const scope = api.resources[scopeName]
-      const unknown = Object.keys(params.canonicalFieldsMap || {}).filter(field => !Object.hasOwn(params.fields, field))
-      if (unknown.length) {
-        throw new Error(`canonicalFieldsMap contains unknown fields for addKnexFields: ${unknown}`)
-      }
-      const fields = snapshotResourceConfiguration(params.fields)
-      const searchSchema = snapshotResourceConfiguration(params.searchSchema || {})
-      const current = composeOptions(scopeName, scope.vars.schemaInfo.descriptor).options
+    // Compile the resource with the additions, so allocation stores enriched definitions.
+    const prepareAdditions = async (scopeName, { fields, searchSchema = {}, canonicalFieldsMap }) => {
+      const current = composeOptions(scopeName, api.resources[scopeName].vars.schemaInfo.descriptor).options
       const candidate = snapshotResourceConfiguration({
         ...current,
         schema: { ...current.schema, ...fields },
         searchSchema: { ...current.searchSchema, ...searchSchema }
       })
       const schemaInfo = await compileOptions(scopeName, candidate)
-      await api.transaction(transaction => registry.allocateFields({
+      const allocation = {
         tenant: tenantId,
         resource: scopeName,
         fields: Object.fromEntries(Object.keys(fields).map(fieldName => [fieldName, {
           definition: schemaInfo.schemaStructure[fieldName] || schemaInfo.computed[fieldName],
           declaration: fields[fieldName],
-          canonicalField: params.canonicalFieldsMap?.[fieldName]
+          canonicalField: canonicalFieldsMap?.[fieldName]
         }])),
         searchSchema
-      }, { transaction }))
+      }
+      return { candidate, schemaInfo, allocation }
+    }
+
+    const publishChange = async (scopeName, { fields = {}, searchSchema = {}, compiled } = {}) => {
       registry.invalidateDescriptor(tenantId, scopeName)
-      const local = runtimeDeclarations.get(scopeName) || {}
-      runtimeDeclarations.set(scopeName, {
-        schema: { ...local.schema, ...fields },
-        searchSchema: { ...local.searchSchema, ...searchSchema }
-      })
-      // The fresh descriptor also carries fields other servers added meanwhile.
+      if (Object.keys(fields).length || Object.keys(searchSchema).length) {
+        const local = runtimeDeclarations.get(scopeName) || {}
+        runtimeDeclarations.set(scopeName, {
+          schema: { ...local.schema, ...fields },
+          searchSchema: { ...local.searchSchema, ...searchSchema }
+        })
+      }
+      // The fresh descriptor also carries changes other servers made meanwhile.
       const descriptor = await registry.getDescriptor(tenantId, scopeName)
-      await publish(scopeName, descriptor, { compiled: { signature: optionsSignature(candidate), schemaInfo } })
+      await publish(scopeName, descriptor, { compiled })
       await notifySchemaChanged(scopeName, descriptor.schemaVersion)
+    }
+
+    addResourceMethod('addKnexFields', async ({ scopeName, params }) => {
+      if (!params?.fields || typeof params.fields !== 'object' || Array.isArray(params.fields)) {
+        throw new Error('fields parameter is required for addKnexFields')
+      }
+      assertFieldNameMap(params.fields, `added fields in '${scopeName}'`)
+      assertFieldNameMap(params.searchSchema, `added search schema in '${scopeName}'`)
+      assertFieldNameMap(params.canonicalFieldsMap, `added canonical fields in '${scopeName}'`)
+      const unknown = Object.keys(params.canonicalFieldsMap || {}).filter(field => !Object.hasOwn(params.fields, field))
+      if (unknown.length) {
+        throw new Error(`canonicalFieldsMap contains unknown fields for addKnexFields: ${unknown}`)
+      }
+      const fields = snapshotResourceConfiguration(params.fields)
+      const searchSchema = snapshotResourceConfiguration(params.searchSchema || {})
+      const { candidate, schemaInfo, allocation } = await prepareAdditions(scopeName, { fields, searchSchema, canonicalFieldsMap: params.canonicalFieldsMap })
+      await api.transaction(transaction => registry.allocateFields(allocation, { transaction }))
+      await publishChange(scopeName, { fields, searchSchema, compiled: { signature: optionsSignature(candidate), schemaInfo } })
+    })
+
+    const retirable = (scopeName, fieldName) => {
+      const definition = api.resources[scopeName].vars.schemaInfo.schemaStructure[fieldName]
+      if (!definition || fieldName === 'id' || definition.virtual === true || definition.belongsTo) {
+        throw new Error(`'${scopeName}.${fieldName}' is not a stored attribute`)
+      }
+      return definition
+    }
+
+    addResourceMethod('retireKnexFields', async ({ scopeName, params }) => {
+      const fields = Array.isArray(params) ? params : params?.fields
+      if (!Array.isArray(fields) || !fields.length) throw new Error('retireKnexFields requires an array of field names')
+      fields.forEach(fieldName => retirable(scopeName, fieldName))
+      await registry.retireFields({ tenant: tenantId, resource: scopeName, fields })
+      await publishChange(scopeName)
     })
 
+    // Change a field's type: copy its values into a new field, then retire it.
+    addResourceMethod('migrateField', async ({ scopeName, params }) => {
+      const { from, to, transform } = params || {}
+      const { name, ...declaration } = to || {}
+      if (typeof from !== 'string' || typeof name !== 'string' || !name) {
+        throw new Error('migrateField requires from and to: { name, ...definition }')
+      }
+      if (transform !== undefined && typeof transform !== 'function') throw new Error('migrateField transform must be a function')
+      const fromDefinition = retirable(scopeName, from)
+      if (fromDefinition.retired) throw new Error(`Field '${scopeName}.${from}' is already retired`)
+      if (declaration.computed || declaration.virtual || declaration.belongsTo || declaration.getter || declaration.setter || declaration.storage) {
+        throw new Error(`migrateField target '${name}' must be a plain stored attribute; add other fields with addKnexFields`)
+      }
+      assertFieldNameMap({ [name]: declaration }, `migrated field in '${scopeName}'`)
+      const fields = snapshotResourceConfiguration({ [name]: declaration })
+      const { schemaInfo, allocation } = await prepareAdditions(scopeName, { fields })
+
+      await api.transaction(async (transaction) => {
+        const descriptor = await registry.allocateFields(allocation, { transaction })
+        await copyFieldValues({ transaction, descriptor, schemaInfo, from, fromDefinition, to: name, transform })
+        await registry.retireFields({ tenant: tenantId, resource: scopeName, fields: [from] }, { transaction })
+      })
+      await publishChange(scopeName, { fields })
+    })
+
+    const copyFieldValues = async ({ transaction, descriptor, schemaInfo, from, fromDefinition, to, transform }) => {
+      const { canonical } = descriptor
+      const source = descriptor.fields[from].slot
+      const target = descriptor.fields[to].slot
+      const idColumn = canonical.logicalIdColumn
+      for (let lastId = null; ;) {
+        const query = transaction(canonical.tableName)
+          .where(canonical.tenantColumn, tenantId)
+          .where(canonical.resourceColumn, descriptor.resource)
+          .orderBy('id')
+          .limit(MIGRATION_BATCH_SIZE)
+          .select('id', idColumn, source)
+        if (lastId !== null) query.where('id', '>', lastId)
+        const rows = await applyDatabaseReadOptions(query)
+        if (!rows.length) return
+        for (const row of rows) {
+          lastId = row.id
+          const value = normalizeStoredFieldValue(row[source], fromDefinition, { fieldName: from, resourceType: descriptor.resource })
+          const next = transform ? await transform(value, { id: String(row[idColumn]) }) : value
+          const rejected = reason => {
+            const message = `Record '${row[idColumn]}' cannot migrate '${from}' to '${to}': ${reason}`
+            return new RestApiValidationError(message, { fields: [to], violations: [{ field: to, rule: 'field_migration', message }] })
+          }
+          const { validatedObject, errors } = await schemaInfo.schemaInstance.patch({ [to]: next ?? null })
+          if (Object.keys(errors).length) throw rejected(Object.values(errors)[0].message)
+          let stored
+          try {
+            stored = translateCanonicalAttributesForStorage({ [to]: validatedObject[to] ?? null }, descriptor, {
+              schemaInfo, databaseClient: knex.client.config.client
+            })
+          } catch (error) {
+            if (error?.type === 'rest_api_validation') throw rejected(error.message)
+            throw error
+          }
+          await transaction(canonical.tableName).where('id', row.id).update({ [target]: stored[target] ?? null })
+        }
+      }
+    }
+
     addResourceMethod('alterKnexFields', async () => {
       throw new Error('alterKnexFields is not supported by AnyAPI Knex plugin yet')
     })

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

@@ -0,0 +1,41 @@
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
+import { getEffectiveSortableFields } from '../lib/querying/query-field-sort-helpers.js'
+import { compileAggregateRequest } from '../lib/querying/aggregate-query.js'
+
+/**
+ * Group a filtered collection and compute measures for each group.
+ * Filters are validated like query filters; permissions are checked as a
+ * query, and row policies and autofilters see queryPurpose 'aggregate'.
+ * Returns plain rows in either format; grouped results are paged.
+ */
+export default async function aggregateMethod ({ params, context, vars, helpers, scope, runHooks, scopeName, api }) {
+  context.method = 'aggregate'
+  context.scopeName = scopeName
+  context.schemaInfo = scope.vars.schemaInfo
+
+  const plan = compileAggregateRequest({
+    params,
+    schemaInfo: context.schemaInfo,
+    scopeName,
+    defaultLimit: vars.queryDefaultLimit,
+    maxLimit: vars.queryMaxLimit
+  })
+  const requestContracts = getRequestContracts({
+    scopeName,
+    schemaInfo: context.schemaInfo,
+    includeDepthLimit: vars.includeDepthLimit,
+    sortableFields: getEffectiveSortableFields(vars)
+  })
+  const validated = validateRequestContractOrThrow(
+    requestContracts.query,
+    { queryParams: { filters: params.queryParams?.filters ?? {} } },
+    'Aggregate filters are invalid'
+  )
+  context.queryParams = { filters: validated.queryParams?.filters || {} }
+
+  context.transaction = params.transaction
+  context.db = context.transaction || api.knex.instance
+
+  await scope.checkPermissions({ method: 'query', originalContext: context })
+  return helpers.dataAggregate({ scopeName, context, runHooks, plan })
+}

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

@@ -2,6 +2,15 @@ import type { Knex } from 'knex'
 
 export type AnyapiSlotPool = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'belongsTo'
 export type AnyapiSlotCounts = Partial<Record<AnyapiSlotPool, number>>
+// Pools whose slots can carry a (tenant_id, resource, slot) index.
+export type AnyapiIndexedSlotPool = 'string' | 'number' | 'boolean' | 'date'
+export type AnyapiIndexedSlotCounts = Partial<Record<AnyapiIndexedSlotPool, number>>
+
+export interface AnyapiSchemaOptions {
+  slots?: AnyapiSlotCounts
+  // Fields declared `indexed: true` take these slots.
+  indexedSlots?: AnyapiIndexedSlotCounts
+}
 
 export interface AnyapiSchemaChange {
   tenant: string
@@ -21,10 +30,12 @@ export class AnyapiRegistry {
   constructor(options: AnyapiRegistryOptions)
   readonly knex: Knex
   readonly cacheSize: number
-  ensureSchema(options?: { slots?: AnyapiSlotCounts }): Promise<void>
+  ensureSchema(options?: AnyapiSchemaOptions): 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>
+export function ensureAnyApiSchema(knex: Knex, options?: AnyapiSchemaOptions): Promise<void>

package/types/plugin-options.d.ts

@@ -1,7 +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'
+import type { AnyapiIndexedSlotCounts, AnyapiRegistry, AnyapiSchemaChange, AnyapiSlotCounts } from './anyapi.js'
 
 export type RestApiPluginOptions = RemovedResourceOptions & {
   format?: ResourceFormat
@@ -50,6 +50,7 @@ export interface RestApiAnyapiKnexPluginOptions extends RestApiKnexPluginOptions
   // false leaves a shared Knex instance open when this API is released.
   ownsKnex?: boolean
   slots?: AnyapiSlotCounts
+  indexedSlots?: AnyapiIndexedSlotCounts
   // 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.

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