@edium/halifax 2.1.0 → 2.2.1

package/dist/core/handlerUtils.d.ts

@@ -0,0 +1,70 @@
+import type { AuthContext, AuthStrategy } from '../auth/AuthStrategy.js';
+import type { CrudHooks, HookContext, MaybePromise } from '../core/hooks.js';
+import { type CrudAction, type ResourceDefinition } from '../core/types.js';
+import type { HttpRequest, HttpResponse, Repository } from '../core/types.js';
+/**
+ * Converts any thrown value to a structured `{ status, code, message, details }` object.
+ * {@link HttpError} subclasses preserve their status; all other errors become 500.
+ */
+export declare function normalizeError(error: unknown): {
+    status: number;
+    code: string;
+    message: string;
+    details?: unknown;
+};
+/**
+ * Serialises a caught error and writes it as a JSON `{ errors: [...] }` response.
+ */
+export declare function sendError(error: unknown, res: HttpResponse): Promise<void>;
+/**
+ * Invokes a data-transforming hook and falls back to `value` when the hook returns void.
+ */
+export declare function applyHook<T>(hook: ((value: T, ctx: HookContext) => MaybePromise<T | void>) | undefined, value: T, ctx: HookContext): Promise<T>;
+/**
+ * Writes a success body as JSON, wrapping it under `envelope` when one is configured.
+ */
+export declare function writeSuccess(res: HttpResponse, status: number, body: unknown, envelope: string | null): void | Promise<void>;
+/**
+ * Parses and validates a raw `:id` route parameter.
+ * @throws {@link BadRequestError} when the value is not a valid integer, UUID, or ObjectId.
+ */
+export declare function parseId(raw: string | undefined): string | number;
+/**
+ * Strips non-writable fields from a request body and rejects unknown fields with a 422.
+ * Fields with `writable: false` are dropped; fields gated by `writeRoles` the caller lacks
+ * are also dropped.
+ * @throws {@link UnprocessableEntityError} for keys not defined on the resource.
+ */
+export declare function filterWritableFields(resource: ResourceDefinition, data: Record<string, unknown>, auth?: AuthContext): Record<string, unknown>;
+/**
+ * Strips fields the caller is not permitted to read based on per-field `readRoles`.
+ * Fast-path returns the record unchanged when no fields carry read restrictions.
+ */
+export declare function filterReadableFields(resource: ResourceDefinition, record: Record<string, unknown>, auth?: AuthContext): Record<string, unknown>;
+/**
+ * Runs the auth strategy for `action` and throws {@link AuthorizationError} when not allowed.
+ */
+export declare function authorizeRequest(req: HttpRequest, resource: ResourceDefinition, action: CrudAction, authStrategy: AuthStrategy): Promise<AuthContext>;
+/**
+ * Reads a single header value by name (case-insensitive).
+ */
+export declare function getHeaderValue(req: HttpRequest, name: string): string | undefined;
+/**
+ * Returns true when the request asks to force-refresh the cache.
+ * For `Cache-Control` this means a `no-cache`/`no-store` directive; for any custom header,
+ * mere presence with a non-empty value triggers the bust.
+ */
+export declare function wantsCacheBust(req: HttpRequest, header: string): boolean;
+/**
+ * Wraps a route handler with Content-Type / Accept checks, error serialisation,
+ * and `X-Correlation-ID` echo-back.
+ */
+export declare function wrap(handler: (req: HttpRequest, res: HttpResponse) => Promise<void>): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+/** Shared context passed to every route-handler registration function. */
+export interface RouteHandlerContext {
+    resource: ResourceDefinition;
+    authStrategy: AuthStrategy;
+    envelope: string | null;
+    hooks: CrudHooks<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>> | undefined;
+    resolveRepo: (req: HttpRequest, auth: AuthContext) => Promise<Repository>;
+}

package/dist/core/handlerUtils.js

@@ -0,0 +1,193 @@
+import { HttpError } from '../errors/HttpError.js';
+import { NotAcceptableError } from '../errors/NotAcceptableError.js';
+import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
+import { UnsupportedMediaTypeError } from '../errors/UnsupportedMediaTypeError.js';
+import { AuthorizationError } from '../errors/AuthorizationError.js';
+import {} from '../core/types.js';
+import { validateId, isValidUuid, isValidObjectId } from '../core/validation.js';
+/** Maps HTTP status codes to machine-readable error code strings. */
+const statusCodeMap = {
+    400: 'BAD_REQUEST',
+    401: 'UNAUTHORIZED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    405: 'METHOD_NOT_ALLOWED',
+    406: 'NOT_ACCEPTABLE',
+    415: 'UNSUPPORTED_MEDIA_TYPE',
+    422: 'UNPROCESSABLE_ENTITY',
+    501: 'NOT_IMPLEMENTED'
+};
+/**
+ * Converts any thrown value to a structured `{ status, code, message, details }` object.
+ * {@link HttpError} subclasses preserve their status; all other errors become 500.
+ */
+export function normalizeError(error) {
+    if (error instanceof HttpError) {
+        return {
+            status: error.status,
+            code: statusCodeMap[error.status] ?? 'INTERNAL_ERROR',
+            message: error.message,
+            details: error.details
+        };
+    }
+    return { status: 500, code: 'INTERNAL_ERROR', message: 'Internal server error' };
+}
+/**
+ * Serialises a caught error and writes it as a JSON `{ errors: [...] }` response.
+ */
+export async function sendError(error, res) {
+    const { status, code, message, details } = normalizeError(error);
+    const item = { code, message };
+    if (details !== undefined)
+        item['details'] = details;
+    await res.status(status).json({ errors: [item] });
+}
+/**
+ * Invokes a data-transforming hook and falls back to `value` when the hook returns void.
+ */
+export async function applyHook(hook, value, ctx) {
+    if (!hook)
+        return value;
+    return (await hook(value, ctx)) ?? value;
+}
+/**
+ * Writes a success body as JSON, wrapping it under `envelope` when one is configured.
+ */
+export function writeSuccess(res, status, body, envelope) {
+    return res.status(status).json(envelope ? { [envelope]: body } : body);
+}
+/**
+ * Parses and validates a raw `:id` route parameter.
+ * @throws {@link BadRequestError} when the value is not a valid integer, UUID, or ObjectId.
+ */
+export function parseId(raw) {
+    validateId(raw);
+    if (typeof raw === 'string' && (isValidUuid(raw) || isValidObjectId(raw)))
+        return raw;
+    return typeof raw === 'string' ? parseInt(raw, 10) : raw;
+}
+/**
+ * Strips non-writable fields from a request body and rejects unknown fields with a 422.
+ * Fields with `writable: false` are dropped; fields gated by `writeRoles` the caller lacks
+ * are also dropped.
+ * @throws {@link UnprocessableEntityError} for keys not defined on the resource.
+ */
+export function filterWritableFields(resource, data, auth) {
+    const fields = resource.fields ?? [];
+    const fieldMap = new Map(fields.map((f) => [f.name, f]));
+    const unknownFields = Object.keys(data).filter((key) => !fieldMap.has(key));
+    if (unknownFields.length) {
+        throw new UnprocessableEntityError(`Unknown field(s): ${unknownFields.join(', ')}.`);
+    }
+    const userRoles = new Set([...(auth?.roles ?? []), ...(auth?.permissions ?? [])]);
+    return Object.fromEntries(Object.entries(data).filter(([key]) => {
+        const field = fieldMap.get(key);
+        if (field?.writable === false)
+            return false;
+        if (field?.writeRoles?.length) {
+            return field.writeRoles.some((r) => userRoles.has(r));
+        }
+        return true;
+    }));
+}
+/**
+ * Strips fields the caller is not permitted to read based on per-field `readRoles`.
+ * Fast-path returns the record unchanged when no fields carry read restrictions.
+ */
+export function filterReadableFields(resource, record, auth) {
+    const fields = resource.fields ?? [];
+    if (!fields.some((f) => (f.readRoles?.length ?? 0) > 0))
+        return record;
+    const fieldMap = new Map(fields.map((f) => [f.name, f]));
+    const userRoles = new Set([...(auth?.roles ?? []), ...(auth?.permissions ?? [])]);
+    return Object.fromEntries(Object.entries(record).filter(([key]) => {
+        const field = fieldMap.get(key);
+        if (!field?.readRoles?.length)
+            return true;
+        return field.readRoles.some((r) => userRoles.has(r));
+    }));
+}
+/**
+ * Runs the auth strategy for `action` and throws {@link AuthorizationError} when not allowed.
+ */
+export async function authorizeRequest(req, resource, action, authStrategy) {
+    const auth = await authStrategy.authenticate(req);
+    const requiredPermissions = resource.requiredPermissions?.[action] ?? [];
+    if (authStrategy.authorize) {
+        const allowed = await authStrategy.authorize({
+            auth,
+            action,
+            resource,
+            requiredPermissions,
+            req
+        });
+        if (!allowed)
+            throw new AuthorizationError();
+        return auth;
+    }
+    if (requiredPermissions.length) {
+        const permissions = new Set(auth.permissions ?? []);
+        const roles = new Set(auth.roles ?? []);
+        const allowed = requiredPermissions.some((permission) => permissions.has(permission) || roles.has(permission));
+        if (!allowed)
+            throw new AuthorizationError();
+    }
+    return auth;
+}
+/**
+ * Reads a single header value by name (case-insensitive).
+ */
+export function getHeaderValue(req, name) {
+    const raw = req.headers[name.toLowerCase()] ?? req.headers[name];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Returns true when the request asks to force-refresh the cache.
+ * For `Cache-Control` this means a `no-cache`/`no-store` directive; for any custom header,
+ * mere presence with a non-empty value triggers the bust.
+ */
+export function wantsCacheBust(req, header) {
+    const value = getHeaderValue(req, header);
+    if (!value)
+        return false;
+    if (header.toLowerCase() === 'cache-control')
+        return /no-cache|no-store/i.test(value);
+    return true;
+}
+function checkContentType(req) {
+    if (!['POST', 'PATCH', 'PUT', 'DELETE'].includes(req.method.toUpperCase()))
+        return;
+    const contentType = getHeaderValue(req, 'content-type') ?? '';
+    if (contentType && !contentType.includes('application/json')) {
+        throw new UnsupportedMediaTypeError();
+    }
+}
+function checkAcceptHeader(req) {
+    const accept = getHeaderValue(req, 'accept') ?? '';
+    if (accept &&
+        !accept.includes('*/*') &&
+        !accept.includes('application/*') &&
+        !accept.includes('application/json')) {
+        throw new NotAcceptableError();
+    }
+}
+/**
+ * Wraps a route handler with Content-Type / Accept checks, error serialisation,
+ * and `X-Correlation-ID` echo-back.
+ */
+export function wrap(handler) {
+    return async (req, res) => {
+        const correlationId = getHeaderValue(req, 'x-correlation-id');
+        if (correlationId)
+            res.setHeader?.('X-Correlation-ID', correlationId);
+        try {
+            checkContentType(req);
+            checkAcceptHeader(req);
+            await handler(req, res);
+        }
+        catch (error) {
+            await sendError(error, res);
+        }
+    };
+}

package/dist/core/handlers/create.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerCreate(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/create.js

@@ -0,0 +1,26 @@
+import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, getHeaderValue, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerCreate(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('POST', basePath, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'create', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        const idempotencyKey = getHeaderValue(req, 'idempotency-key');
+        const createOptions = idempotencyKey ? { idempotencyKey } : undefined;
+        const hookCtx = { auth, resource, req };
+        const rawItems = (Array.isArray(req.body) ? req.body : [req.body ?? {}]).map((item) => filterWritableFields(resource, item, auth));
+        const items = hooks?.beforeCreate
+            ? await Promise.all(rawItems.map((d) => applyHook(hooks.beforeCreate, d, hookCtx)))
+            : rawItems;
+        if (items.length === 1) {
+            const rawResult = await repo.createOne(items[0], createOptions);
+            const result = await applyHook(hooks?.afterCreate, rawResult, hookCtx);
+            await writeSuccess(res, 201, filterReadableFields(resource, result, auth), envelope);
+            return;
+        }
+        const rawResults = await repo.createMany(items, createOptions);
+        const results = hooks?.afterCreate
+            ? await Promise.all(rawResults.map((r) => applyHook(hooks.afterCreate, r, hookCtx)))
+            : rawResults;
+        await writeSuccess(res, 201, results.map((r) => filterReadableFields(resource, r, auth)), envelope);
+    }));
+}

package/dist/core/handlers/deleteMany.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerDeleteMany(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/deleteMany.js

@@ -0,0 +1,24 @@
+import { validateAdvancedQuery } from '../../core/validation.js';
+import { NotImplementedError } from '../../errors/NotImplementedError.js';
+import { UnprocessableEntityError } from '../../errors/UnprocessableEntityError.js';
+import { applyHook, authorizeRequest, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerDeleteMany(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('DELETE', basePath, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'deleteMany', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        if (!repo.deleteMany)
+            throw new NotImplementedError('This resource does not support deleteMany.');
+        const hookCtx = { auth, resource, req };
+        const body = (req.body ?? {});
+        const query = { ...body };
+        validateAdvancedQuery(resource, query);
+        if (!query.where?.length)
+            throw new UnprocessableEntityError('deleteMany requires at least one WHERE filter to prevent unintended bulk deletes.');
+        if (hooks?.beforeDeleteMany)
+            await hooks.beforeDeleteMany(query, hookCtx);
+        const rawResult = await repo.deleteMany(query);
+        const result = await applyHook(hooks?.afterDeleteMany, rawResult, hookCtx);
+        await writeSuccess(res, 200, result, envelope);
+    }));
+}

package/dist/core/handlers/deleteOne.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerDeleteOne(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/deleteOne.js

@@ -0,0 +1,19 @@
+import { NotFoundError } from '../../errors/NotFoundError.js';
+import { authorizeRequest, parseId, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerDeleteOne(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('DELETE', `${basePath}/:id`, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'deleteOne', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        const id = parseId(req.params['id']);
+        const hookCtx = { auth, resource, req };
+        if (hooks?.beforeDeleteOne)
+            await hooks.beforeDeleteOne(id, hookCtx);
+        const deleted = await repo.deleteOne(id);
+        if (!deleted)
+            throw new NotFoundError();
+        if (hooks?.afterDeleteOne)
+            await hooks.afterDeleteOne(id, hookCtx);
+        await writeSuccess(res, 200, { deleted: true }, envelope);
+    }));
+}

package/dist/core/handlers/query.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerQuery(server: HttpServer, basePath: string, queryBuilderPath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/query.js

@@ -0,0 +1,23 @@
+import { validateAdvancedQuery } from '../../core/validation.js';
+import { NotImplementedError } from '../../errors/NotImplementedError.js';
+import { applyHook, authorizeRequest, filterReadableFields, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerQuery(server, basePath, queryBuilderPath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('POST', `${basePath}/${queryBuilderPath}`, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'readManyWithQueryBuilder', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        if (!repo.executeQuery)
+            throw new NotImplementedError('This resource does not support the query builder.');
+        const hookCtx = { auth, resource, req };
+        const body = (req.body ?? {});
+        const parsedQuery = { ...body };
+        const query = await applyHook(hooks?.beforeQuery, parsedQuery, hookCtx);
+        validateAdvancedQuery(resource, query);
+        const rawResult = await repo.executeQuery(query);
+        const result = await applyHook(hooks?.afterQuery, rawResult, hookCtx);
+        await writeSuccess(res, 200, {
+            ...result,
+            results: result.results.map((r) => filterReadableFields(resource, r, auth))
+        }, envelope);
+    }));
+}

package/dist/core/handlers/readMany.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerReadMany(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/readMany.js

@@ -0,0 +1,18 @@
+import { parseListOptions } from '../../core/queryString.js';
+import { applyHook, authorizeRequest, filterReadableFields, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerReadMany(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('GET', basePath, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'readMany', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        const hookCtx = { auth, resource, req };
+        const parsedOptions = parseListOptions(req.query, resource);
+        const listOptions = await applyHook(hooks?.beforeReadMany, parsedOptions, hookCtx);
+        const rawResult = await repo.getMany(listOptions);
+        const result = await applyHook(hooks?.afterReadMany, rawResult, hookCtx);
+        await writeSuccess(res, 200, {
+            ...result,
+            results: result.results.map((r) => filterReadableFields(resource, r, auth))
+        }, envelope);
+    }));
+}

package/dist/core/handlers/readOne.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerReadOne(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/readOne.js

@@ -0,0 +1,23 @@
+import { parseListOptions } from '../../core/queryString.js';
+import { NotFoundError } from '../../errors/NotFoundError.js';
+import { applyHook, authorizeRequest, filterReadableFields, parseId, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerReadOne(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('GET', `${basePath}/:id`, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'readOne', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        const id = parseId(req.params['id']);
+        const hookCtx = { auth, resource, req };
+        if (hooks?.beforeReadOne)
+            await hooks.beforeReadOne(id, hookCtx);
+        const listOptions = parseListOptions(req.query, resource);
+        const rawResult = await repo.getOne(id, {
+            fields: listOptions.fields,
+            include: listOptions.include
+        });
+        if (!rawResult)
+            throw new NotFoundError();
+        const result = await applyHook(hooks?.afterReadOne, rawResult, hookCtx);
+        await writeSuccess(res, 200, filterReadableFields(resource, result, auth), envelope);
+    }));
+}

package/dist/core/handlers/updateMany.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerUpdateMany(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/updateMany.js

@@ -0,0 +1,34 @@
+import { validateAdvancedQuery } from '../../core/validation.js';
+import { NotImplementedError } from '../../errors/NotImplementedError.js';
+import { UnprocessableEntityError } from '../../errors/UnprocessableEntityError.js';
+import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerUpdateMany(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('PATCH', basePath, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'updateMany', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        if (!repo.updateMany)
+            throw new NotImplementedError('This resource does not support updateMany.');
+        const hookCtx = { auth, resource, req };
+        const { update, ...queryBody } = (req.body ?? {});
+        const filteredUpdate = filterWritableFields(resource, (update ?? {}), auth);
+        if (!Object.keys(filteredUpdate).length)
+            throw new UnprocessableEntityError('updateMany requires at least one writable field in the update payload.');
+        const query = { ...queryBody };
+        validateAdvancedQuery(resource, query);
+        if (!query.where?.length)
+            throw new UnprocessableEntityError('updateMany requires at least one WHERE filter to prevent unintended bulk updates.');
+        if (hooks?.beforeUpdateMany)
+            await hooks.beforeUpdateMany(query, filteredUpdate, hookCtx);
+        const rawResult = await repo.updateMany(query, filteredUpdate);
+        const result = await applyHook(hooks?.afterUpdateMany, rawResult, hookCtx);
+        await writeSuccess(res, 200, {
+            ...result,
+            ...(result.results
+                ? {
+                    results: result.results.map((r) => filterReadableFields(resource, r, auth))
+                }
+                : {})
+        }, envelope);
+    }));
+}

package/dist/core/handlers/updateOne.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerUpdateOne(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/updateOne.js

@@ -0,0 +1,20 @@
+import { NotFoundError } from '../../errors/NotFoundError.js';
+import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, parseId, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerUpdateOne(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('PATCH', `${basePath}/:id`, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'updateOne', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        const id = parseId(req.params['id']);
+        const hookCtx = { auth, resource, req };
+        const rawBody = filterWritableFields(resource, (req.body ?? {}), auth);
+        const body = hooks?.beforeUpdateOne
+            ? ((await hooks.beforeUpdateOne(id, rawBody, hookCtx)) ?? rawBody)
+            : rawBody;
+        const rawResult = await repo.updateOne(id, body);
+        if (!rawResult)
+            throw new NotFoundError();
+        const result = await applyHook(hooks?.afterUpdateOne, rawResult, hookCtx);
+        await writeSuccess(res, 200, filterReadableFields(resource, result, auth), envelope);
+    }));
+}

package/dist/core/handlers/upsertOne.d.ts

@@ -0,0 +1,3 @@
+import type { HttpServer } from '../../core/types.js';
+import { type RouteHandlerContext } from '../../core/handlerUtils.js';
+export declare function registerUpsertOne(server: HttpServer, basePath: string, ctx: RouteHandlerContext): void;

package/dist/core/handlers/upsertOne.js

@@ -0,0 +1,20 @@
+import { NotImplementedError } from '../../errors/NotImplementedError.js';
+import { applyHook, authorizeRequest, filterReadableFields, filterWritableFields, parseId, wrap, writeSuccess } from '../../core/handlerUtils.js';
+export function registerUpsertOne(server, basePath, ctx) {
+    const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
+    server.registerRoute('PUT', `${basePath}/:id`, wrap(async (req, res) => {
+        const auth = await authorizeRequest(req, resource, 'upsertOne', authStrategy);
+        const repo = await resolveRepo(req, auth);
+        if (!repo.upsertOne)
+            throw new NotImplementedError('This resource does not support upsert.');
+        const id = parseId(req.params['id']);
+        const hookCtx = { auth, resource, req };
+        const rawBody = filterWritableFields(resource, (req.body ?? {}), auth);
+        const body = hooks?.beforeUpsertOne
+            ? ((await hooks.beforeUpsertOne(id, rawBody, hookCtx)) ?? rawBody)
+            : rawBody;
+        const rawResult = await repo.upsertOne(id, body);
+        const result = await applyHook(hooks?.afterUpsertOne, rawResult, hookCtx);
+        await writeSuccess(res, 200, filterReadableFields(resource, result, auth), envelope);
+    }));
+}