@cube-nl/dmp-sdk 0.0.0-stage → 1.0.0-rc.4

package/dist/preview.js

@@ -0,0 +1,803 @@
+import { DmpError } from './errors.js';
+import { buildQuery } from './query.js';
+const RESOURCE_NAME = /^[a-z][a-z0-9_]*$/;
+const OPERATORS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'like', 'ilike', 'is', 'between'];
+const SYMBOLS = [['>=', 'gte'], ['<=', 'lte'], ['<>', 'neq'], ['>', 'gt'], ['<', 'lt'], ['=', 'eq']];
+const FUNCTIONS = ['count', 'sum', 'avg', 'min', 'max'];
+const UNITS = ['day', 'week', 'month', 'quarter', 'year'];
+const MAX_FILTERS = 20;
+const MAX_DIMENSIONS = 5;
+const MAX_GROUPS = 1000;
+const MAX_IN_VALUES = 200;
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+const CONTRACT = '1.0';
+/**
+ * The preview's data: every resource of the mock data, in memory, changed by create, update and
+ * delete until the page is reloaded. It answers as the REST face does — the same envelope, the same
+ * paging, the same refusals as `DmpError` — and never touches the network.
+ */
+export class PreviewStore {
+    manifest;
+    guard;
+    tables = new Map();
+    constructor(data, manifest = null, 
+    /** Runs before every call; throw to refuse it (the preview's signed-out state). */
+    guard = () => undefined) {
+        this.manifest = manifest;
+        this.guard = guard;
+        for (const [key, resource] of Object.entries(unwrap(data))) {
+            // Not a resource: a comment key such as `_about`, or a value that is no object.
+            if (typeof resource !== 'object' || resource === null || Array.isArray(resource)) {
+                continue;
+            }
+            const name = typeof resource.schema?.name === 'string' && resource.schema.name !== '' ? resource.schema.name : key;
+            if (RESOURCE_NAME.test(name)) {
+                this.tables.set(name, table(name, resource));
+            }
+        }
+    }
+    resourceNames() {
+        return [...this.tables.keys()];
+    }
+    resource(name) {
+        if (!RESOURCE_NAME.test(name)) {
+            throw new TypeError(`'${name}' is not a resource name: cube/api names match [a-z][a-z0-9_]*.`);
+        }
+        // Answered asynchronously, like the REST face: a refusal is a rejected promise, never a throw.
+        const run = (action, work) => Promise.resolve().then(() => work(this.authorize(name, action)));
+        const list = (query = {}) => run('list', (table) => listRows(table, query));
+        const pages = async function* (query = {}) {
+            let number = query.page?.number ?? 1;
+            while (true) {
+                const page = await list({ ...query, page: { ...query.page, number } });
+                yield page;
+                if (page.meta.page.number >= page.meta.page.pages || page.data.length === 0) {
+                    return;
+                }
+                number = page.meta.page.number + 1;
+            }
+        };
+        return {
+            name,
+            list,
+            pages,
+            async *all(query = {}) {
+                for await (const page of pages(query)) {
+                    yield* page.data;
+                }
+            },
+            get: (id, query = {}) => run('get', (table) => getRow(table, id, query)),
+            aggregate: (query) => run('aggregate', (table) => aggregateRows(table, query)),
+            create: (body, options = {}) => run('create', (table) => createRow(table, body, options)),
+            update: (id, body, options = {}) => run('update', (table) => updateRow(table, id, body, options)),
+            delete: (id, options = {}) => run('delete', (table) => deleteRow(table, id, options)),
+            operation: (id, operation, _input, _options) => run('get', (table) => {
+                findRow(table, id);
+                throw noSuchOperation(operation);
+            }),
+            collectionOperation: (operation) => run('list', () => {
+                throw noSuchOperation(operation);
+            }),
+        };
+    }
+    /**
+     * Unknown resource first (404, as the REST face answers it), then the manifest: live, the app's
+     * OAuth client is capped to its `uses`, so the preview refuses what the live app would.
+     */
+    authorize(name, action) {
+        this.guard();
+        const table = this.tables.get(name);
+        if (table === undefined) {
+            throw problem(404, 'not_found', `Unknown API resource [${name}].`);
+        }
+        const uses = this.manifest?.uses;
+        if (uses !== undefined && !(uses[name] ?? []).includes(action)) {
+            throw problem(403, 'client_scope_exceeded', `This app may not ${action} '${name}': add it to "uses" in cube-app.json.`);
+        }
+        return table;
+    }
+}
+function unwrap(data) {
+    const wrapped = data.resources;
+    if (Object.keys(data).length === 1 && isObject(wrapped) && !('rows' in wrapped) && !('schema' in wrapped)) {
+        return wrapped;
+    }
+    return data;
+}
+function table(name, resource) {
+    const schema = resource.schema ?? {};
+    const rows = (resource.rows ?? []).map((row) => clone(row));
+    const fields = new Map();
+    const declared = Array.isArray(schema.fields)
+        ? schema.fields.map((field) => [field.name, field])
+        : Object.entries((schema.fields ?? {}));
+    for (const [fieldName, definition] of declared) {
+        fields.set(fieldName, field(fieldName, definition));
+    }
+    // Without a schema the rows are the schema: every key any row carries is a field.
+    for (const row of fields.size === 0 ? rows : []) {
+        for (const key of Object.keys(row)) {
+            if (!fields.has(key)) {
+                fields.set(key, { name: key, types: [], nullable: true });
+            }
+        }
+    }
+    const names = [...fields.keys()];
+    // A malformed key or entry is ignored as if absent, so one bad line in a mock never breaks the preview.
+    const choiceEntries = (isObject(schema.choices) ? Object.entries(schema.choices) : []).filter((entry) => isObject(entry[1]) && Array.isArray(entry[1].values));
+    const readonly = new Set([
+        'id',
+        ...(schema.readonly ?? []),
+        ...declared.filter(([, definition]) => definition.readonly === true).map(([fieldName]) => fieldName),
+        ...choiceEntries
+            .filter(([, choice]) => choice.writable === false)
+            .map(([fieldName]) => fieldName),
+    ]);
+    const choices = new Map();
+    for (const [fieldName, definition] of declared) {
+        if (Array.isArray(definition.enum)) {
+            choices.set(fieldName, definition.enum);
+        }
+    }
+    for (const [fieldName, choice] of choiceEntries) {
+        choices.set(fieldName, choice.values);
+    }
+    const known = (list) => Array.isArray(list) ? list.filter((item) => typeof item === 'string' && fields.has(item)) : null;
+    return {
+        name,
+        fields,
+        filterable: known(schema.filters) ?? names,
+        groupable: known(schema.groupable) ?? names,
+        aggregatable: new Map(isObject(schema.aggregatable)
+            ? Object.entries(schema.aggregatable)
+                .filter(([fieldName, allowed]) => fields.has(fieldName) && Array.isArray(allowed))
+                .map(([fieldName, allowed]) => [fieldName, [...allowed]])
+            : names.map((fieldName) => [fieldName, [...FUNCTIONS]])),
+        choices,
+        writable: new Set(names.filter((fieldName) => !readonly.has(fieldName))),
+        summary: (known(schema.summary_fields) ?? []).length > 0 ? known(schema.summary_fields) : names,
+        rows,
+        versions: new Map(rows.map((row) => [key(row.id), 1])),
+        replays: new Map(),
+    };
+}
+function field(name, definition) {
+    const raw = definition.type;
+    const list = typeof raw === 'string' ? raw.split('|') : Array.isArray(raw) ? [...raw] : [];
+    return {
+        name,
+        types: list.filter((type) => type !== 'null' && type !== ''),
+        nullable: definition.nullable === true || list.includes('null'),
+    };
+}
+/**
+ * The query is turned into the exact query string the live client would send (`buildQuery`), then
+ * read back the way the REST face reads it. The preview so refuses what the API refuses, and a
+ * mistake `buildQuery` catches before a request (a bare array as a filter) is the same TypeError.
+ */
+function parse(table, query) {
+    return new URLSearchParams(buildQuery(table.name, query));
+}
+function listRows(table, query) {
+    const params = parse(table, query);
+    const selected = selection(table, params);
+    const filters = readFilters(table, params);
+    const sort = readSort(table, params);
+    const { size, number } = readPage(params);
+    const omitted = relations(table, params);
+    let rows = table.rows.filter((row) => filters.every((filter) => matches(table, row, filter)));
+    if (sort.length > 0) {
+        rows = [...rows].sort((a, b) => {
+            for (const { field: name, descending } of sort) {
+                const order = compare(a[name], b[name]);
+                if (order !== 0) {
+                    return descending ? -order : order;
+                }
+            }
+            return 0;
+        });
+    }
+    const total = rows.length;
+    const data = rows.slice((number - 1) * size, number * size).map((row) => project(row, selected));
+    const page = { size, number, total, pages: Math.max(1, Math.ceil(total / size)) };
+    return { ...response(200, data, meta(table, page, omitted)), meta: { ...meta(table, page, omitted), page } };
+}
+function getRow(table, id, query) {
+    const params = parse(table, query);
+    const selected = selection(table, params);
+    const omitted = relations(table, params);
+    const row = findRow(table, id);
+    return response(200, project(row, selected), meta(table, null, omitted), version(table, row));
+}
+function selection(table, params) {
+    const parameter = `fields[${table.name}]`;
+    const raw = params.get(parameter);
+    if (raw === null || raw === '') {
+        return table.summary;
+    }
+    const requested = raw.split(',').map((item) => item.trim());
+    const unknown = requested.filter((item) => !table.fields.has(item));
+    if (unknown.length > 0) {
+        throw problem(422, 'query_invalid', `Unknown ${parameter}: ${unknown.join(', ')}.`, {
+            [parameter]: [`Allowed values: ${[...table.fields.keys()].join(', ')}.`],
+        });
+    }
+    return requested;
+}
+/**
+ * Mock data names no relations, so the preview cannot follow one. A requested include or count
+ * comes back the way the REST face reports a relation the caller may not see: in `meta.omitted`,
+ * never as an empty list that looks like data.
+ */
+function relations(_table, params) {
+    const list = (key) => (params.get(key) ?? '').split(',').filter((item) => item !== '');
+    return [...new Set([...list('include'), ...list('with_count')])];
+}
+function readFilters(table, params) {
+    const filters = [];
+    const entries = [];
+    params.forEach((value, name) => entries.push([name, value]));
+    for (const [key, value] of entries) {
+        const match = /^filter\[([^\]]+)\](?:\[([^\]]+)\])?$/.exec(key);
+        if (match === null) {
+            continue;
+        }
+        const name = match[1];
+        if (!table.filterable.includes(name)) {
+            throw problem(422, 'query_invalid', `Unknown filter: ${name}.`, {
+                filter: [`Allowed values: ${table.filterable.join(', ')}.`],
+            }, 'not_filterable');
+        }
+        filters.push(match[2] === undefined ? fromSymbol(name, value) : operand(name, match[2], value));
+    }
+    if (filters.length > MAX_FILTERS) {
+        throw problem(422, 'query_invalid', `A query takes at most ${MAX_FILTERS} filters.`, {
+            filter: [`Sent ${filters.length}; the limit is ${MAX_FILTERS}.`],
+        });
+    }
+    return filters;
+}
+function fromSymbol(name, value) {
+    for (const [symbol, operator] of SYMBOLS) {
+        if (value.startsWith(symbol)) {
+            return { field: name, operator, value: value.slice(symbol.length) };
+        }
+    }
+    return { field: name, operator: 'eq', value };
+}
+function operand(name, operator, value) {
+    if (!OPERATORS.includes(operator)) {
+        throw problem(422, 'query_invalid', `Unknown filter operator: ${operator}.`, {
+            filter: [`Allowed operators: ${OPERATORS.join(', ')}.`],
+        });
+    }
+    if (operator === 'between' && value.split(',').length !== 2) {
+        throw problem(422, 'query_invalid', `filter[${name}][between] takes exactly 2 values.`, {
+            filter: [`Write filter[${name}][between]=low,high. Received ${value.split(',').length} value(s).`],
+        });
+    }
+    if (operator === 'in' && value.split(',').length > MAX_IN_VALUES) {
+        throw problem(422, 'query_invalid', `filter[${name}][in] takes at most ${MAX_IN_VALUES} values.`, {
+            filter: [`Sent ${value.split(',').length}; the limit is ${MAX_IN_VALUES}.`],
+        });
+    }
+    if (operator === 'is' && value !== 'null' && value !== 'not_null') {
+        throw problem(422, 'query_invalid', `filter[${name}][is] takes null or not_null.`, {
+            filter: [`Received: ${value}.`],
+        });
+    }
+    return { field: name, operator, value };
+}
+function matches(table, row, filter) {
+    const actual = row[filter.field];
+    const typed = (value) => coerce(table.fields.get(filter.field), value.trim());
+    switch (filter.operator) {
+        case 'eq':
+            return same(actual, typed(filter.value));
+        case 'neq':
+            // As SQL's `<>`: a null is neither equal nor unequal.
+            return actual != null && !same(actual, typed(filter.value));
+        case 'gt':
+            return actual != null && compare(actual, typed(filter.value)) > 0;
+        case 'gte':
+            return actual != null && compare(actual, typed(filter.value)) >= 0;
+        case 'lt':
+            return actual != null && compare(actual, typed(filter.value)) < 0;
+        case 'lte':
+            return actual != null && compare(actual, typed(filter.value)) <= 0;
+        case 'in':
+            return filter.value.split(',').some((item) => same(actual, typed(item)));
+        case 'between': {
+            const [low, high] = filter.value.split(',').map(typed);
+            return actual != null && compare(actual, low) >= 0 && compare(actual, high) <= 0;
+        }
+        case 'like':
+        case 'ilike':
+            return typeof actual === 'string' && like(actual, filter.value);
+        case 'is':
+            return filter.value === 'null' ? actual == null : actual != null;
+        default:
+            return false;
+    }
+}
+/** As the engine: a substring match where `%` is a wildcard and `_` a literal, case-insensitive. */
+function like(actual, pattern) {
+    const source = pattern.split('%').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+    return new RegExp(source, 'iu').test(actual);
+}
+function readSort(table, params) {
+    const raw = params.get('sort');
+    if (raw === null || raw === '') {
+        return [];
+    }
+    const sort = raw.split(',').map((item) => item.trim()).filter((item) => item !== '').map((item) => ({
+        field: item.replace(/^[-+]/, ''),
+        descending: item.startsWith('-'),
+    }));
+    const unknown = sort.map((item) => item.field).filter((name) => !table.fields.has(name));
+    if (unknown.length > 0) {
+        throw problem(422, 'query_invalid', `Unknown sort: ${unknown.join(', ')}.`, {
+            sort: [`Allowed values: ${[...table.fields.keys()].join(', ')}.`],
+        }, 'not_sortable');
+    }
+    return sort;
+}
+function readPage(params) {
+    const integer = (parameter) => {
+        const raw = params.get(parameter);
+        if (raw === null || raw === '') {
+            return null;
+        }
+        if (!/^\d+$/.test(raw)) {
+            throw problem(422, 'query_invalid', `${parameter} must be a positive integer.`, {
+                [parameter]: ['Expected a positive integer.'],
+            });
+        }
+        return Number(raw);
+    };
+    const size = integer('page[size]') ?? DEFAULT_PAGE_SIZE;
+    // Refused rather than clamped, as on the REST face.
+    if (size > MAX_PAGE_SIZE) {
+        throw problem(422, 'cardinality_exceeded', `page[size] may not exceed ${MAX_PAGE_SIZE}.`, {
+            'page.size': [`The maximum page size is ${MAX_PAGE_SIZE}.`],
+        });
+    }
+    return { size: Math.max(1, size), number: Math.max(1, integer('page[number]') ?? 1) };
+}
+function aggregateRows(table, query) {
+    const params = parse(table, query);
+    // As the wire reads a query: fn entries, then group entries, then filters.
+    const rawFn = (params.get('fn') ?? '').trim();
+    if (rawFn === '') {
+        throw problem(422, 'query_invalid', 'fn is required: name at least one aggregation function.', {
+            fn: [`Expected e.g. fn=count or fn=sum(field). ${aggregatableHint(table)}`],
+        });
+    }
+    const functions = rawFn.split(',').map((item) => item.trim());
+    const readers = functions.map((fn) => aggregator(table, fn));
+    rejectDuplicates(functions, 'fn');
+    const rawGroup = (params.get('group') ?? '').trim();
+    const groups = rawGroup === '' ? [] : rawGroup.split(',').map((item) => item.trim());
+    // Before the entries: the repair for too many dimensions is a coarser question, not a fixed name.
+    if (groups.length > MAX_DIMENSIONS) {
+        throw problem(422, 'cardinality_exceeded', `group may not exceed ${MAX_DIMENSIONS} dimensions, ${groups.length} given.`, { group: [`Use at most ${MAX_DIMENSIONS} dimensions.`] });
+    }
+    const dimensions = groups.map((group) => dimension(table, group));
+    rejectDuplicates(groups, 'group');
+    const filters = readFilters(table, params);
+    const buckets = new Map();
+    for (const row of table.rows.filter((candidate) => filters.every((filter) => matches(table, candidate, filter)))) {
+        const key = {};
+        for (const [index, group] of groups.entries()) {
+            key[group] = dimensions[index](row);
+        }
+        const id = JSON.stringify(Object.values(key));
+        const bucket = buckets.get(id) ?? { key, rows: [] };
+        bucket.rows.push(row);
+        buckets.set(id, bucket);
+    }
+    if (groups.length === 0 && buckets.size === 0) {
+        buckets.set('[]', { key: {}, rows: [] });
+    }
+    if (buckets.size > MAX_GROUPS) {
+        throw problem(422, 'cardinality_exceeded', 'The grouping produces more groups than the configured maximum.', {
+            groepen: [
+                'The grouping produces more groups than the configured maximum.',
+                `Allowed values: groepeer grover, of filter eerst; maximaal ${MAX_GROUPS} groepen.`,
+            ],
+        }, 'too_many_groups');
+    }
+    const ordered = [...buckets.values()].sort((a, b) => {
+        for (const group of groups) {
+            const order = compare(a.key[group], b.key[group]);
+            if (order !== 0) {
+                return order;
+            }
+        }
+        return 0;
+    });
+    const data = ordered.map(({ key, rows }) => {
+        const result = { ...key };
+        for (const [index, fn] of functions.entries()) {
+            result[fn] = readers[index](rows);
+        }
+        return result;
+    });
+    return response(200, data, { ...meta(table, null, []), groups: data.length });
+}
+/** As live refuses it: two entries would collapse into one response key. */
+function rejectDuplicates(entries, parameter) {
+    const duplicates = [...new Set(entries.filter((entry, index) => entries.indexOf(entry) !== index))];
+    if (duplicates.length > 0) {
+        throw problem(422, 'query_invalid', `Duplicate ${parameter} entry: ${duplicates.join(', ')}.`, {
+            [parameter]: [`List each ${parameter} entry once.`],
+        });
+    }
+}
+function aggregatableHint(table) {
+    return table.aggregatable.size === 0
+        ? 'This resource has no aggregatable fields; only bare count is available.'
+        : `Aggregatable fields: ${[...table.aggregatable.keys()].join(', ')}.`;
+}
+function aggregator(table, fn) {
+    const call = /^([a-z]+)\(([a-z0-9_]+)\)$/.exec(fn);
+    if (call === null && !/^[a-z]+$/.test(fn)) {
+        throw problem(422, 'query_invalid', `Unparseable fn entry: ${fn}.`, {
+            fn: ['Expected `count` or `function(field)`, e.g. sum(field).'],
+        });
+    }
+    const name = call === null ? fn : call[1];
+    const target = call === null ? null : call[2];
+    if (!FUNCTIONS.includes(name)) {
+        throw problem(422, 'query_invalid', `Unknown aggregation function: ${name}.`, {
+            fn: [`Allowed values: ${FUNCTIONS.join(', ')}.`],
+        });
+    }
+    if (target === null) {
+        if (name !== 'count') {
+            throw problem(422, 'query_invalid', `${name} must be applied to a field, e.g. ${name}(field).`, {
+                fn: [aggregatableHint(table)],
+            });
+        }
+        return (rows) => rows.length;
+    }
+    const allowed = table.aggregatable.get(target);
+    if (allowed === undefined) {
+        throw problem(422, 'query_invalid', `Unknown aggregatable field: ${target}.`, { fn: [aggregatableHint(table)] });
+    }
+    if (!allowed.includes(name)) {
+        throw problem(422, 'query_invalid', `${name} is not allowed on ${target}.`, {
+            fn: [`Allowed functions for ${target}: ${allowed.join(', ')}.`],
+        });
+    }
+    return (rows) => {
+        const values = rows.map((row) => row[target]).filter((value) => value != null);
+        const numbers = values.map(Number).filter((value) => Number.isFinite(value));
+        switch (name) {
+            case 'count':
+                // Live emits count(*) whatever the field, so count(field) counts the group's rows, nulls included.
+                return rows.length;
+            case 'sum':
+                return numbers.length === 0 ? null : numbers.reduce((sum, value) => sum + value, 0);
+            case 'avg':
+                return numbers.length === 0 ? null : numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
+            case 'min':
+                return values.length === 0 ? null : values.reduce((low, value) => (compare(value, low) < 0 ? value : low));
+            default:
+                return values.length === 0 ? null : values.reduce((high, value) => (compare(value, high) > 0 ? value : high));
+        }
+    };
+}
+function dimension(table, group) {
+    const parts = group.split('.');
+    if (parts.length > 2) {
+        throw problem(422, 'query_invalid', `Unparseable group entry: ${group}.`, {
+            group: ['Expected `field` or `field.unit`, e.g. published_at.month.'],
+        });
+    }
+    const [name, truncation] = parts;
+    if (!table.groupable.includes(name)) {
+        throw problem(422, 'query_invalid', `Unknown group: ${name}.`, {
+            group: [`Allowed values: ${table.groupable.join(', ')}.`],
+        }, 'not_groupable');
+    }
+    if (truncation === undefined) {
+        return (row) => row[name] ?? null;
+    }
+    if (!UNITS.includes(truncation)) {
+        throw problem(422, 'query_invalid', `Unknown truncation unit: ${truncation}.`, {
+            group: [`Allowed values: ${UNITS.join(', ')}.`],
+        });
+    }
+    return (row) => bucket(row[name], truncation);
+}
+/** The date as written (first 10 characters), never shifted through a time zone; null when it is not a date. */
+function bucket(value, unit) {
+    const match = typeof value === 'string' ? /^(\d{4})-(\d{2})-(\d{2})/.exec(value) : null;
+    if (match === null) {
+        return null;
+    }
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+        return null;
+    }
+    switch (unit) {
+        case 'day':
+            return match[0];
+        case 'week': {
+            // ISO week: the Thursday of the Monday-based week decides the ISO year.
+            const thursday = new Date(date.getTime() + (3 - ((date.getUTCDay() + 6) % 7)) * 86_400_000);
+            const isoYear = thursday.getUTCFullYear();
+            const week = 1 + Math.floor((thursday.getTime() - Date.UTC(isoYear, 0, 1)) / (7 * 86_400_000));
+            return `${isoYear}-W${String(week).padStart(2, '0')}`;
+        }
+        case 'month':
+            return match[0].slice(0, 7);
+        case 'quarter':
+            return `${match[1]}-Q${Math.ceil(month / 3)}`;
+        case 'year':
+            return match[1];
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------------------------
+function createRow(table, body, options) {
+    const selected = options.fields === undefined ? table.summary : selection(table, parse(table, { fields: options.fields }));
+    const fingerprint = JSON.stringify([body, options.fields ?? null]);
+    if (options.idempotencyKey !== undefined) {
+        const earlier = table.replays.get(options.idempotencyKey);
+        if (earlier !== undefined) {
+            if (earlier.body !== fingerprint) {
+                throw problem(422, 'validation_failed', 'This Idempotency-Key was already used with a different '
+                    + 'request body. Use a new key, or resend the original body.');
+            }
+            return { ...earlier.response, replayed: true };
+        }
+    }
+    const values = validate(table, body);
+    const row = { id: nextId(table), ...values };
+    for (const name of table.fields.keys()) {
+        if (!(name in row)) {
+            row[name] = null;
+        }
+    }
+    table.rows.push(row);
+    table.versions.set(key(row.id), 1);
+    const created = response(201, project(row, selected), meta(table, null, []), version(table, row));
+    if (options.idempotencyKey !== undefined) {
+        table.replays.set(options.idempotencyKey, { body: fingerprint, response: created });
+    }
+    return created;
+}
+function updateRow(table, id, body, options) {
+    const selected = options.fields === undefined ? table.summary : selection(table, parse(table, { fields: options.fields }));
+    const row = findRow(table, id);
+    checkVersion(table, row, options.ifMatch);
+    Object.assign(row, validate(table, body));
+    table.versions.set(key(row.id), (table.versions.get(key(row.id)) ?? 1) + 1);
+    return response(200, project(row, selected), meta(table, null, []), version(table, row));
+}
+function deleteRow(table, id, options) {
+    const row = findRow(table, id);
+    checkVersion(table, row, options.ifMatch);
+    table.rows.splice(table.rows.indexOf(row), 1);
+    table.versions.delete(key(row.id));
+    return response(204, null, null);
+}
+/**
+ * The REST face's two refusals for a body: a key that is not writable (422 `query_invalid`, per
+ * field) before any value is looked at, then a value of the wrong type (422 `validation_failed`).
+ */
+function validate(table, body) {
+    const writable = [...table.writable];
+    const message = writable.length === 0
+        ? 'This resource declares no writable fields.'
+        : `Writable fields: ${writable.join(', ')}.`;
+    if (!isObject(body) || Object.keys(body).length === 0) {
+        throw problem(422, 'validation_failed', 'The request body must be a JSON object naming at least one writable field.', {
+            body: [message],
+        });
+    }
+    const refused = Object.keys(body).filter((name) => !table.writable.has(name));
+    if (refused.length > 0) {
+        throw problem(422, 'query_invalid', `Unknown or read-only fields: ${refused.join(', ')}.`, Object.fromEntries(refused.map((name) => [name, [message]])));
+    }
+    const errors = {};
+    for (const [name, value] of Object.entries(body)) {
+        const definition = table.fields.get(name);
+        const problemText = typeError(definition, value) ?? choiceError(table, definition, name, value);
+        if (problemText !== null) {
+            errors[name] = [problemText];
+        }
+    }
+    if (Object.keys(errors).length > 0) {
+        throw problem(422, 'validation_failed', 'The request body failed validation.', errors);
+    }
+    return clone(body);
+}
+/** Laravel's `in` rule: a value outside the field's allowed values. Runs only after the type check passed. */
+function choiceError(table, definition, name, value) {
+    const allowed = table.choices.get(name);
+    if (allowed === undefined || (value === null && definition?.nullable === true) || allowed.includes(value)) {
+        return null;
+    }
+    return `The selected ${name.replace(/_/g, ' ')} is invalid.`;
+}
+/** Laravel's rules and wording for the one declared type, as the REST face's TypeRules applies them. */
+function typeError(definition, value) {
+    if (definition === undefined || definition.types.length !== 1) {
+        return null;
+    }
+    if (value === null) {
+        return definition.nullable ? null : messageFor(definition);
+    }
+    const valid = (() => {
+        switch (definition.types[0]) {
+            case 'string':
+                return typeof value === 'string';
+            case 'integer':
+                return (typeof value === 'number' && Number.isInteger(value))
+                    || (typeof value === 'string' && /^[+-]?\d+$/.test(value.trim()));
+            case 'number':
+                return (typeof value === 'number' && Number.isFinite(value))
+                    || (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)));
+            case 'boolean':
+                return [true, false, 0, 1, '0', '1'].includes(value);
+            case 'array':
+            case 'object':
+                return typeof value === 'object';
+            default:
+                return true;
+        }
+    })();
+    return valid ? null : messageFor(definition);
+}
+function messageFor(definition) {
+    const attribute = definition.name.replace(/_/g, ' ');
+    const kind = {
+        string: 'a string',
+        integer: 'an integer',
+        number: 'a number',
+        boolean: 'true or false',
+        array: 'an array',
+        object: 'an array',
+    };
+    return `The ${attribute} field must be ${kind[definition.types[0]] ?? 'valid'}.`;
+}
+function checkVersion(table, row, ifMatch) {
+    if (ifMatch === undefined) {
+        return;
+    }
+    if (ifMatch.startsWith('W/')) {
+        throw new TypeError('ifMatch takes recordVersion (X-Dmp-Record-Version), not the weak ETag.');
+    }
+    const current = version(table, row);
+    if (ifMatch !== current) {
+        throw problem(409, 'conflict', 'The record changed since the version you sent.', undefined, undefined, {
+            'X-Dmp-Record-Version': current,
+        });
+    }
+}
+function nextId(table) {
+    const ids = table.rows.map((row) => row.id);
+    if (ids.length > 0 && ids.every((id) => typeof id === 'string') && ids.some((id) => !/^\d+$/.test(id))) {
+        return crypto.randomUUID();
+    }
+    return ids.reduce((max, id) => Math.max(max, Number(id) || 0), 0) + 1;
+}
+// ---------------------------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------------------------
+function findRow(table, id) {
+    const wanted = key(id);
+    if (wanted === '' || wanted === '.' || wanted === '..') {
+        throw new TypeError(`${table.name}: '${wanted}' is not an id.`);
+    }
+    const row = table.rows.find((candidate) => key(candidate.id) === wanted);
+    if (row === undefined) {
+        throw problem(404, 'not_found', `No such ${table.name} record.`);
+    }
+    return row;
+}
+function noSuchOperation(operation) {
+    return problem(404, 'not_found', `No such operation [${operation}]. The preview runs no custom operations.`);
+}
+function project(row, selected) {
+    const result = {};
+    for (const name of selected) {
+        result[name] = name in row ? clone(row[name]) : null;
+    }
+    return result;
+}
+function version(table, row) {
+    return `"preview-${key(row.id)}-${table.versions.get(key(row.id)) ?? 1}"`;
+}
+function meta(table, page, omitted) {
+    return { resource: table.name, contract: CONTRACT, page, groups: null, omitted, pruned: [], forbidden_fields: [] };
+}
+function response(status, data, body, recordVersion = null) {
+    const headers = new Headers({ 'X-Dmp-Preview': 'true' });
+    if (recordVersion !== null) {
+        headers.set('X-Dmp-Record-Version', recordVersion);
+    }
+    return {
+        status,
+        data,
+        meta: body,
+        headers,
+        etag: null,
+        recordVersion,
+        location: null,
+        replayed: false,
+        rateLimit: { limit: null, remaining: null, reset: null },
+    };
+}
+/** A refusal shaped exactly as the REST face writes it, so the app's error handling is the same code. */
+function problem(status, code, detail, errors, reason, headers = {}) {
+    return new DmpError(status, new Headers({ 'Content-Type': 'application/problem+json', ...headers }), {
+        type: `https://docs.cube.nl/dmp-api/problems/${code}`,
+        title: code.replace(/_/g, ' '),
+        status,
+        code,
+        ...(reason !== undefined ? { reason } : {}),
+        detail,
+        ...(errors !== undefined ? { errors } : {}),
+    });
+}
+/** A filter value from the query string, typed after the field it compares against. */
+function coerce(definition, value) {
+    const type = definition?.types[0];
+    if ((type === 'integer' || type === 'number') && value !== '' && Number.isFinite(Number(value))) {
+        return Number(value);
+    }
+    if (type === 'boolean') {
+        if (value === '1' || value === 'true') {
+            return true;
+        }
+        if (value === '0' || value === 'false') {
+            return false;
+        }
+    }
+    return value;
+}
+function same(actual, expected) {
+    if (actual == null) {
+        return false;
+    }
+    if (typeof actual === 'boolean' && typeof expected !== 'boolean') {
+        return (actual ? '1' : '0') === String(expected) || String(actual) === String(expected);
+    }
+    if (typeof actual === 'number' && typeof expected === 'string') {
+        return String(actual) === expected;
+    }
+    return actual === expected || (typeof actual !== 'object' && String(actual) === String(expected));
+}
+/** Nulls first, numbers as numbers, everything else as text (ISO dates sort correctly as text). */
+function compare(a, b) {
+    if (a == null || b == null) {
+        return a == null ? (b == null ? 0 : -1) : 1;
+    }
+    if (typeof a === 'number' && typeof b === 'number') {
+        return a - b;
+    }
+    if (typeof a === 'boolean' || typeof b === 'boolean') {
+        return Number(a === true || a === 1 || a === '1') - Number(b === true || b === 1 || b === '1');
+    }
+    const left = String(a);
+    const right = String(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function key(id) {
+    return id === null || id === undefined ? '' : String(id);
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function clone(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}