@async/db 0.2.0

package/dist/shared/csv.js

@@ -0,0 +1,149 @@
+import { dbError } from './errors.js';
+export function parseCsvRecords(text, filePath = 'CSV file') {
+    const rows = parseCsvRows(text);
+    const headerRow = rows.shift();
+    if (!headerRow || headerRow.every((cell) => cell.value.trim() === '')) {
+        throw dbError('CSV_MISSING_HEADER', `${filePath} must start with a header row.`, {
+            status: 400,
+            hint: 'Add a first row with column names, for example: id,name,email.',
+        });
+    }
+    const headers = headerRow.map((cell, index) => ({
+        rawName: cell.value.trim(),
+        fieldName: fieldNameFromHeader(cell.value, index),
+    }));
+    const fieldNames = uniqueFieldNames(headers.map((header) => header.fieldName));
+    return rows
+        .filter((row) => row.some((cell) => cell.value.trim() !== ''))
+        .map((row) => {
+        const record = {};
+        for (const [index, header] of headers.entries()) {
+            const value = coerceCsvValue(row[index] ?? { value: '', quoted: false }, header.rawName);
+            if (value !== undefined) {
+                record[fieldNames[index]] = value;
+            }
+        }
+        return record;
+    });
+}
+export function parseCsvRows(text) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    let wasQuoted = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (quoted) {
+            if (char === '"' && text[index + 1] === '"') {
+                field += '"';
+                index += 1;
+            }
+            else if (char === '"') {
+                quoted = false;
+            }
+            else {
+                field += char;
+            }
+            continue;
+        }
+        if (char === '"' && field === '') {
+            quoted = true;
+            wasQuoted = true;
+            continue;
+        }
+        if (char === ',') {
+            pushField();
+            continue;
+        }
+        if (char === '\n') {
+            pushField();
+            pushRow();
+            continue;
+        }
+        if (char === '\r') {
+            if (text[index + 1] === '\n') {
+                index += 1;
+            }
+            pushField();
+            pushRow();
+            continue;
+        }
+        field += char;
+    }
+    if (quoted) {
+        throw dbError('CSV_UNTERMINATED_QUOTE', 'CSV file has an unterminated quoted field.', {
+            status: 400,
+            hint: 'Close the quoted field with another double quote, or escape embedded quotes as "".',
+        });
+    }
+    pushField();
+    pushRow();
+    return rows;
+    function pushField() {
+        row.push({
+            value: wasQuoted ? field : field.trim(),
+            quoted: wasQuoted,
+        });
+        field = '';
+        wasQuoted = false;
+    }
+    function pushRow() {
+        if (row.length > 1 || row[0]?.value !== '') {
+            rows.push(row);
+        }
+        row = [];
+    }
+}
+function fieldNameFromHeader(header, index) {
+    const trimmed = String(header).trim();
+    if (/^[a-z_$][A-Za-z0-9_$]*$/.test(trimmed)) {
+        return trimmed;
+    }
+    if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(trimmed)) {
+        return trimmed.charAt(0).toLowerCase() + trimmed.slice(1);
+    }
+    const words = trimmed.match(/[A-Za-z0-9]+/g) ?? [];
+    const name = words.map((word, wordIndex) => {
+        const lower = word.toLowerCase();
+        return wordIndex === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1);
+    }).join('');
+    if (!name) {
+        return `column${index + 1}`;
+    }
+    return /^\d/.test(name) ? `_${name}` : name;
+}
+function uniqueFieldNames(names) {
+    const counts = new Map();
+    return names.map((name) => {
+        const count = counts.get(name) ?? 0;
+        counts.set(name, count + 1);
+        return count === 0 ? name : `${name}${count + 1}`;
+    });
+}
+function coerceCsvValue(cell, headerName) {
+    const value = cell.quoted ? cell.value : cell.value.trim();
+    if (value === '') {
+        return undefined;
+    }
+    if (cell.quoted || isStringLikeHeader(headerName)) {
+        return value;
+    }
+    const lower = value.toLowerCase();
+    if (lower === 'true') {
+        return true;
+    }
+    if (lower === 'false') {
+        return false;
+    }
+    if (lower === 'null') {
+        return undefined;
+    }
+    if (/^[+-]?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) {
+        return Number(value);
+    }
+    return value;
+}
+function isStringLikeHeader(headerName) {
+    return /\b(id|uuid|guid|zip|postal|phone|tel|code)\b/i.test(String(headerName).replaceAll(/[^A-Za-z0-9]+/g, ' '));
+}

package/dist/shared/errors.d.ts

@@ -0,0 +1,40 @@
+export declare class DbError extends Error {
+    code: string;
+    status: number;
+    hint?: string;
+    details?: unknown;
+    constructor(code: string, message: string, options?: DbErrorOptions);
+}
+export type DbErrorOptions = {
+    status?: number;
+    hint?: string;
+    details?: unknown;
+};
+type ErrorLike = {
+    code?: string;
+    message?: string;
+    hint?: string;
+    details?: unknown;
+};
+export declare function dbError(code: string, message: string, options?: DbErrorOptions): DbError;
+export declare function serializeError(error: ErrorLike, fallbackCode?: string): {
+    error: {
+        code: string;
+        message: string;
+        hint: string;
+        details: unknown;
+    };
+};
+export declare function graphqlError(error: ErrorLike, fallbackCode?: string): {
+    message: string;
+    extensions: {
+        code: string;
+        hint: string;
+        details: unknown;
+    };
+};
+export declare function describeValue(value: unknown): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array";
+export declare function listChoices(values: unknown[], options?: {
+    max?: number;
+}): string;
+export {};

package/dist/shared/errors.js

@@ -0,0 +1,55 @@
+export class DbError extends Error {
+    code;
+    status;
+    hint;
+    details;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'DbError';
+        this.code = code;
+        this.status = options.status ?? 400;
+        this.hint = options.hint;
+        this.details = options.details;
+    }
+}
+export function dbError(code, message, options = {}) {
+    return new DbError(code, message, options);
+}
+export function serializeError(error, fallbackCode = 'DB_ERROR') {
+    return {
+        error: {
+            code: error.code ?? fallbackCode,
+            message: error.message ?? String(error),
+            hint: error.hint,
+            details: error.details,
+        },
+    };
+}
+export function graphqlError(error, fallbackCode = 'GRAPHQL_ERROR') {
+    return {
+        message: error.message ?? String(error),
+        extensions: {
+            code: error.code ?? fallbackCode,
+            hint: error.hint,
+            details: error.details,
+        },
+    };
+}
+export function describeValue(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+export function listChoices(values, options = {}) {
+    const max = options.max ?? 8;
+    const list = [...values].filter(Boolean).slice(0, max);
+    if (list.length === 0) {
+        return '(none)';
+    }
+    const suffix = values.length > max ? `, and ${values.length - max} more` : '';
+    return list.map((value) => `"${value}"`).join(', ') + suffix;
+}

package/dist/shared/fs-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function readText(filePath: string): Promise<string>;
+export declare function writeText(filePath: string, content: string): Promise<boolean>;
+export declare function resolveFrom(baseDir: string, maybeRelative: string): string;
+export declare function toPosixPath(value: string): string;

package/dist/shared/fs-utils.js

@@ -0,0 +1,30 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function readText(filePath) {
+    return readFile(filePath, 'utf8');
+}
+export async function writeText(filePath, content) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    try {
+        if ((await readFile(filePath, 'utf8')) === content) {
+            return false;
+        }
+    }
+    catch (error) {
+        const fsError = error;
+        if (fsError.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await writeFile(filePath, content, 'utf8');
+    return true;
+}
+export function resolveFrom(baseDir, maybeRelative) {
+    if (path.isAbsolute(maybeRelative)) {
+        return maybeRelative;
+    }
+    return path.resolve(baseDir, maybeRelative);
+}
+export function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}

package/dist/shared/jsonc.d.ts

@@ -0,0 +1,2 @@
+export declare function parseJsonc<TValue = unknown>(text: string, filename?: string): TValue;
+export declare function stripJsonc(text: string): string;

package/dist/shared/jsonc.js

@@ -0,0 +1,99 @@
+export function parseJsonc(text, filename = 'JSONC input') {
+    try {
+        return JSON.parse(stripJsonc(text));
+    }
+    catch (error) {
+        error.message = `${filename}: ${error.message}`;
+        throw error;
+    }
+}
+export function stripJsonc(text) {
+    const withoutBom = text.replace(/^\uFEFF/, '');
+    return stripTrailingCommas(stripComments(withoutBom));
+}
+function stripComments(text) {
+    let output = '';
+    let inString = false;
+    let quote = '';
+    let escaping = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (inString) {
+            output += char;
+            if (escaping) {
+                escaping = false;
+            }
+            else if (char === '\\') {
+                escaping = true;
+            }
+            else if (char === quote) {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            inString = true;
+            quote = char;
+            output += char;
+            continue;
+        }
+        if (char === '/' && next === '/') {
+            while (index < text.length && text[index] !== '\n') {
+                index += 1;
+            }
+            output += '\n';
+            continue;
+        }
+        if (char === '/' && next === '*') {
+            index += 2;
+            while (index < text.length && !(text[index] === '*' && text[index + 1] === '/')) {
+                output += text[index] === '\n' ? '\n' : ' ';
+                index += 1;
+            }
+            index += 1;
+            continue;
+        }
+        output += char;
+    }
+    return output;
+}
+function stripTrailingCommas(text) {
+    let output = '';
+    let inString = false;
+    let quote = '';
+    let escaping = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (inString) {
+            output += char;
+            if (escaping) {
+                escaping = false;
+            }
+            else if (char === '\\') {
+                escaping = true;
+            }
+            else if (char === quote) {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            inString = true;
+            quote = char;
+            output += char;
+            continue;
+        }
+        if (char === ',') {
+            let cursor = index + 1;
+            while (cursor < text.length && /\s/.test(text[cursor])) {
+                cursor += 1;
+            }
+            if (text[cursor] === '}' || text[cursor] === ']') {
+                continue;
+            }
+        }
+        output += char;
+    }
+    return output;
+}

package/dist/shared/mock.d.ts

@@ -0,0 +1,40 @@
+type MockDelay = {
+    minMs?: number;
+    min?: number;
+    maxMs?: number;
+    max?: number;
+};
+type NormalizedMockDelay = {
+    minMs: number;
+    maxMs: number;
+};
+type MockErrorConfig = {
+    rate?: number;
+    probability?: number;
+    status?: number;
+    message?: string;
+};
+type MockConfig = {
+    delay?: number | [number, number] | MockDelay | false;
+    delayMs?: number | [number, number] | MockDelay | false;
+    errors?: number | MockErrorConfig | false | null;
+    error?: number | MockErrorConfig | false | null;
+};
+type RuntimeConfigWithMock = {
+    mock?: MockConfig | false | null;
+    chaos?: MockConfig | false | null;
+    server?: {
+        apiBase?: string;
+    };
+};
+type MockErrorResponse = {
+    status: number;
+    body: {
+        error: string;
+        mock: true;
+    };
+};
+export declare function runMockBehavior(config: RuntimeConfigWithMock, url?: URL | null): Promise<MockErrorResponse | null>;
+export declare function normalizeMockDelay(value: MockConfig['delay']): NormalizedMockDelay;
+export declare function pickDelayMs(delay: Partial<NormalizedMockDelay>, random?: () => number): number;
+export {};

package/dist/shared/mock.js

@@ -0,0 +1,83 @@
+export async function runMockBehavior(config, url = null) {
+    const mock = config.mock ?? config.chaos;
+    if (!mock || shouldSkipMock(config, url)) {
+        return null;
+    }
+    const delay = normalizeMockDelay(mock.delay ?? mock.delayMs);
+    if (delay.maxMs > 0) {
+        await sleep(pickDelayMs(delay));
+    }
+    const error = normalizeMockError(mock.errors ?? mock.error);
+    if (error.rate > 0 && Math.random() < error.rate) {
+        return {
+            status: error.status,
+            body: {
+                error: error.message,
+                mock: true,
+            },
+        };
+    }
+    return null;
+}
+export function normalizeMockDelay(value) {
+    if (!value) {
+        return {
+            minMs: 0,
+            maxMs: 0,
+        };
+    }
+    if (Array.isArray(value)) {
+        return normalizeDelayNumbers(value[0], value[1]);
+    }
+    if (typeof value === 'number') {
+        return normalizeDelayNumbers(value, value);
+    }
+    return normalizeDelayNumbers(value.minMs ?? value.min ?? 0, value.maxMs ?? value.max ?? value.minMs ?? value.min ?? 0);
+}
+export function pickDelayMs(delay, random = Math.random) {
+    const minMs = Math.max(0, Number(delay.minMs ?? 0));
+    const maxMs = Math.max(minMs, Number(delay.maxMs ?? minMs));
+    return Math.round(minMs + (maxMs - minMs) * random());
+}
+function normalizeMockError(value) {
+    if (!value) {
+        return {
+            rate: 0,
+            status: 503,
+            message: 'Mock chaos error',
+        };
+    }
+    if (typeof value === 'number') {
+        return {
+            rate: clampRate(value),
+            status: 503,
+            message: 'Mock chaos error',
+        };
+    }
+    return {
+        rate: clampRate(value.rate ?? value.probability ?? 0),
+        status: Number(value.status ?? 503),
+        message: String(value.message ?? 'Mock chaos error'),
+    };
+}
+function normalizeDelayNumbers(min, max) {
+    const minMs = Math.max(0, Number(min ?? 0));
+    const maxMs = Math.max(minMs, Number(max ?? minMs));
+    return {
+        minMs,
+        maxMs,
+    };
+}
+function clampRate(value) {
+    return Math.min(1, Math.max(0, Number(value)));
+}
+function shouldSkipMock(config, url) {
+    return url?.pathname === normalizeBasePath(config.server?.apiBase ?? '/__db');
+}
+function normalizeBasePath(value) {
+    const path = `/${String(value ?? '').replace(/^\/+/, '').replace(/\/+$/, '')}`;
+    return path === '/' ? '' : path;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/shared/names.d.ts

@@ -0,0 +1,28 @@
+type NamedResource = {
+    name: string;
+};
+type ResolveResourceResult<TResource> = {
+    resource: TResource | null;
+    matchedName: string | null;
+    candidates: string[];
+};
+export declare function pascalCase(value: string): string;
+export declare function camelCase(value: string): string;
+export declare function kebabCase(value: string): string;
+export declare function resourceNameCandidates(value: string): string[];
+export declare function resolveResource<TResource>(resources: Map<string, TResource>, requestedName: string): ResolveResourceResult<TResource>;
+export declare function resourceAliasCollisions(resources: Array<string | NamedResource> | Map<string, NamedResource>): {
+    alias: string;
+    resources: string[];
+}[];
+export declare function resourceAliasCollisionGroups(resources: Array<string | NamedResource> | Map<string, NamedResource>): {
+    alias: string;
+    aliases: string[];
+    resources: string[];
+    candidates: Record<string, string[]>;
+}[];
+export declare function resourceConfigValue<TValue>(values: Record<string, TValue> | null | undefined, resourceName: string): TValue | undefined;
+export declare function singularResourceName(resourceName: string): string;
+export declare function typeNameForResource(resourceName: string, kind?: string): string;
+export declare function routePathForResource(resourceName: string): string;
+export {};

package/dist/shared/names.js

@@ -0,0 +1,127 @@
+const IRREGULAR_SINGULARS = new Map([
+    ['people', 'person'],
+    ['children', 'child'],
+    ['settings', 'settings'],
+]);
+export function pascalCase(value) {
+    return words(value)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+export function camelCase(value) {
+    const parts = words(value);
+    return parts
+        .map((word, index) => {
+        if (index === 0) {
+            return word;
+        }
+        return word.charAt(0).toUpperCase() + word.slice(1);
+    })
+        .join('');
+}
+export function kebabCase(value) {
+    return words(value).join('-');
+}
+export function resourceNameCandidates(value) {
+    const exact = String(value);
+    return unique([
+        exact,
+        camelCase(exact),
+        kebabCase(exact),
+    ]);
+}
+export function resolveResource(resources, requestedName) {
+    const candidates = resourceNameCandidates(requestedName);
+    for (const candidate of candidates) {
+        if (resources.has(candidate)) {
+            return {
+                resource: resources.get(candidate),
+                matchedName: candidate,
+                candidates,
+            };
+        }
+    }
+    return {
+        resource: null,
+        matchedName: null,
+        candidates,
+    };
+}
+export function resourceAliasCollisions(resources) {
+    const aliasResources = new Map();
+    const resourceList = Array.isArray(resources) ? resources : [...resources.values()];
+    for (const resource of resourceList) {
+        const resourceName = typeof resource === 'string' ? resource : resource.name;
+        for (const alias of resourceNameCandidates(resourceName)) {
+            const names = aliasResources.get(alias) ?? new Set();
+            names.add(resourceName);
+            aliasResources.set(alias, names);
+        }
+    }
+    return [...aliasResources.entries()]
+        .map(([alias, names]) => ({
+        alias,
+        resources: [...names].sort(),
+    }))
+        .filter((collision) => collision.resources.length > 1)
+        .sort((left, right) => left.alias.localeCompare(right.alias));
+}
+export function resourceAliasCollisionGroups(resources) {
+    const groups = new Map();
+    for (const collision of resourceAliasCollisions(resources)) {
+        const key = collision.resources.join('\0');
+        const group = groups.get(key) ?? {
+            alias: collision.alias,
+            aliases: [],
+            resources: collision.resources,
+            candidates: Object.fromEntries(collision.resources.map((resource) => [resource, resourceNameCandidates(resource)])),
+        };
+        group.aliases.push(collision.alias);
+        groups.set(key, group);
+    }
+    return [...groups.values()];
+}
+export function resourceConfigValue(values, resourceName) {
+    if (!values || typeof values !== 'object') {
+        return undefined;
+    }
+    for (const candidate of resourceNameCandidates(resourceName)) {
+        if (Object.prototype.hasOwnProperty.call(values, candidate)) {
+            return values[candidate];
+        }
+    }
+    return undefined;
+}
+export function singularResourceName(resourceName) {
+    const normalized = resourceName.toLowerCase();
+    if (IRREGULAR_SINGULARS.has(normalized)) {
+        return IRREGULAR_SINGULARS.get(normalized);
+    }
+    if (normalized.endsWith('ies') && normalized.length > 3) {
+        return `${resourceName.slice(0, -3)}y`;
+    }
+    if (normalized.endsWith('ses') || normalized.endsWith('xes') || normalized.endsWith('ches') || normalized.endsWith('shes')) {
+        return resourceName.slice(0, -2);
+    }
+    if (normalized.endsWith('s') && !normalized.endsWith('ss')) {
+        return resourceName.slice(0, -1);
+    }
+    return resourceName;
+}
+export function typeNameForResource(resourceName, kind = 'collection') {
+    const base = kind === 'collection' ? singularResourceName(resourceName) : resourceName;
+    return pascalCase(base);
+}
+export function routePathForResource(resourceName) {
+    return `/${kebabCase(resourceName)}`;
+}
+function words(value) {
+    return String(value)
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.toLowerCase());
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/shared/operations.d.ts

@@ -0,0 +1,32 @@
+export type OperationVariables = Record<string, unknown>;
+export type OperationTemplateRecord = Record<string, unknown>;
+export type OperationTemplate = string | OperationTemplateRecord;
+export type NormalizedOperation = {
+    kind?: 'graphql';
+    name?: string;
+    ref?: string;
+    method?: string;
+    path?: string;
+    query?: string | OperationVariables;
+    body?: unknown;
+    variables?: OperationVariables;
+    operationName?: string | null;
+};
+export type RegisteredOperation = NormalizedOperation & {
+    name: string;
+    ref: string;
+};
+export type OperationRequestResult = {
+    kind?: 'graphql';
+    ref?: string;
+    query?: string;
+    method?: string;
+    path?: string;
+    body?: unknown;
+    variables?: OperationVariables;
+    operationName?: string | null;
+};
+export declare function normalizeOperationTemplate(input: OperationTemplate): NormalizedOperation;
+export declare function canonicalOperation(input: OperationTemplate): NormalizedOperation;
+export declare function operationRequest(input: OperationTemplate, variables?: OperationVariables): OperationRequestResult;
+export declare function stableStringify(value: unknown): string;