@async/db 0.2.0

package/dist/jsonc.js

@@ -0,0 +1 @@
+export { parseJsonc, stripJsonc } from './shared/jsonc.js';

package/dist/kv.d.ts

@@ -0,0 +1,24 @@
+export type KvStoreClient = {
+  get(key: string): unknown | Promise<unknown>;
+  set(key: string, value: string): unknown | Promise<unknown>;
+  close?: () => void | Promise<void>;
+  end?: () => void | Promise<void>;
+  quit?: () => void | Promise<void>;
+  disconnect?: () => void | Promise<void>;
+};
+
+export type KvStoreOptions = {
+  client: KvStoreClient;
+  prefix?: string;
+  close?: boolean | ((client: KvStoreClient) => void | Promise<void>);
+};
+
+export function kvStore(options: KvStoreOptions): unknown;
+export const kvStoreCapabilities: {
+  writable: true;
+  persistence: 'kv';
+  atomicity: 'resource';
+  liveEvents: true;
+  staticExport: false;
+  production: 'small-app';
+};

package/dist/kv.js

@@ -0,0 +1 @@
+export { kvStore, kvStoreCapabilities, } from './integrations/kv.js';

package/dist/mock.d.ts

@@ -0,0 +1 @@
+export { normalizeMockDelay, pickDelayMs, runMockBehavior } from './shared/mock.js';

package/dist/mock.js

@@ -0,0 +1 @@
+export { normalizeMockDelay, pickDelayMs, runMockBehavior } from './shared/mock.js';

package/dist/names.d.ts

@@ -0,0 +1 @@
+export { camelCase, kebabCase, pascalCase, resolveResource, resourceAliasCollisionGroups, resourceAliasCollisions, resourceConfigValue, resourceNameCandidates, routePathForResource, singularResourceName, typeNameForResource, } from './shared/names.js';

package/dist/names.js

@@ -0,0 +1 @@
+export { camelCase, kebabCase, pascalCase, resolveResource, resourceAliasCollisionGroups, resourceAliasCollisions, resourceConfigValue, resourceNameCandidates, routePathForResource, singularResourceName, typeNameForResource, } from './shared/names.js';

package/dist/operations.d.ts

@@ -0,0 +1,3 @@
+export { buildOperationManifest, hashOperation, operationClientContract } from './features/operations/index.js';
+export { createDbOperationHandler } from './features/operations/runtime.js';
+export { normalizeOperationTemplate, operationRequest } from './shared/operations.js';

package/dist/operations.js

@@ -0,0 +1,3 @@
+export { buildOperationManifest, hashOperation, operationClientContract } from './features/operations/index.js';
+export { createDbOperationHandler } from './features/operations/runtime.js';
+export { normalizeOperationTemplate, operationRequest } from './shared/operations.js';

package/dist/postgres.d.ts

@@ -0,0 +1,24 @@
+export type PostgresStoreClient = {
+  query(sql: string, params?: unknown[]): Promise<{ rows?: Array<Record<string, unknown>> }> | { rows?: Array<Record<string, unknown>> };
+  close?: () => void | Promise<void>;
+  end?: () => void | Promise<void>;
+};
+
+export type PostgresStoreOptions = {
+  client: PostgresStoreClient;
+  schema?: string;
+  table?: string;
+  namespace?: string;
+  migrate?: boolean;
+  close?: boolean | ((client: PostgresStoreClient) => void | Promise<void>);
+};
+
+export function postgresStore(options: PostgresStoreOptions): unknown;
+export const postgresStoreCapabilities: {
+  writable: true;
+  persistence: 'postgres';
+  atomicity: 'resource';
+  liveEvents: true;
+  staticExport: false;
+  production: 'small-app';
+};

package/dist/postgres.js

@@ -0,0 +1 @@
+export { postgresStore, postgresStoreCapabilities, } from './integrations/postgres.js';

package/dist/redis.d.ts

@@ -0,0 +1,14 @@
+import type { KvStoreClient, KvStoreOptions } from './kv.d.ts';
+
+export type RedisStoreClient = KvStoreClient;
+export type RedisStoreOptions = KvStoreOptions;
+
+export function redisStore(options: RedisStoreOptions): unknown;
+export const redisStoreCapabilities: {
+  writable: true;
+  persistence: 'kv';
+  atomicity: 'resource';
+  liveEvents: true;
+  staticExport: false;
+  production: 'small-app';
+};

package/dist/redis.js

@@ -0,0 +1 @@
+export { redisStore, redisStoreCapabilities, } from './integrations/kv.js';

package/dist/rest/formats.d.ts

@@ -0,0 +1,80 @@
+type RestFormatTarget = 'resource' | 'manifest';
+type RestResource = {
+    name: string;
+    kind?: string;
+    routePath?: string;
+    [key: string]: unknown;
+};
+type RestRoutes = {
+    manifestPath?: string;
+    manifestJsonPath?: string;
+    manifestHtmlPath?: string;
+    manifestMarkdownPath?: string;
+    [key: string]: unknown;
+};
+type RestRenderContext = {
+    db?: unknown;
+    resource?: RestResource;
+    resourceName?: string;
+    data: unknown;
+    manifest?: unknown;
+    format?: string;
+    request?: unknown;
+    url?: URL;
+    routes?: RestRoutes;
+    target?: RestFormatTarget;
+    [key: string]: unknown;
+};
+type RestRenderer = (context: RestRenderContext) => unknown;
+type RestFormatObject = {
+    mediaTypes?: string | string[];
+    contentType?: string;
+    render?: RestRenderer;
+    renderResource?: RestRenderer;
+    renderManifest?: RestRenderer;
+    [key: string]: unknown;
+};
+type RestFormatInput = string | RestRenderer | RestFormatObject | null | undefined;
+type RestConfig = {
+    rest?: {
+        formats?: Record<string, RestFormatInput> & {
+            default?: RestFormatInput;
+        };
+    };
+    [key: string]: unknown;
+};
+type RestFormatDefinition = {
+    key?: string;
+    alias?: string;
+    mediaTypes: string[];
+    contentType?: string;
+    renderResource?: RestRenderer;
+    renderManifest?: RestRenderer;
+};
+type RestFormatRegistry = Record<string, RestFormatDefinition>;
+type ResolvedRestFormat = {
+    key: string;
+    contentType: string;
+    renderer: RestRenderer;
+};
+type RestFormatMetadata = {
+    extension: string;
+    mediaTypes: string[];
+    contentType: string;
+    manifestPath: string;
+};
+type HeaderBag = {
+    get?: (name: string) => string | null;
+    [key: string]: unknown;
+};
+type HeaderRequest = {
+    headers?: HeaderBag | null;
+};
+export declare function normalizeRestFormatRegistry(config?: RestConfig): RestFormatRegistry;
+export declare function negotiateRestFormat(config: RestConfig, request: HeaderRequest, target?: RestFormatTarget): string;
+export declare function resolveRestFormat(config: RestConfig, format: string | null | undefined, target?: RestFormatTarget): ResolvedRestFormat | null;
+export declare function availableRestFormats(config?: RestConfig, target?: RestFormatTarget | null): string[];
+export declare function restFormatMetadata(config?: RestConfig, routes?: RestRoutes): Record<string, RestFormatMetadata>;
+export declare function manifestPathForFormat(routes: RestRoutes | undefined, format: string): string;
+export declare function renderMarkdownJson(title: string, value: unknown, metadata?: Array<readonly [string, unknown]>): string;
+export {};

package/dist/rest/formats.js

@@ -0,0 +1,318 @@
+import { renderJsonViewer } from '../web/json-viewer.js';
+const BUILT_IN_FORMATS = {
+    json: {
+        mediaTypes: ['application/json'],
+        contentType: 'application/json; charset=utf-8',
+        renderResource: ({ data }) => `${JSON.stringify(data, null, 2)}\n`,
+        renderManifest: ({ data }) => `${JSON.stringify(data, null, 2)}\n`,
+    },
+    html: {
+        mediaTypes: ['text/html'],
+        contentType: 'text/html; charset=utf-8',
+        renderResource: ({ data, url }) => renderJsonViewer(data, { title: jsonViewerTitle(url) }),
+        renderManifest: ({ data }) => renderJsonViewer(data, { title: 'db viewer manifest' }),
+    },
+    md: {
+        mediaTypes: ['text/markdown'],
+        contentType: 'text/markdown; charset=utf-8',
+        renderResource: ({ resource, data }) => renderMarkdownJson(resource.name, data, [
+            ['Resource', resource.name],
+            ['Kind', resource.kind],
+            ['Route', resource.routePath],
+        ]),
+        renderManifest: ({ data, routes }) => renderMarkdownJson('db viewer manifest', data, [
+            ['Kind', 'db.viewerManifest'],
+            ['JSON', routes?.manifestJsonPath ?? manifestPathForFormat(routes, 'json')],
+        ]),
+    },
+};
+export function normalizeRestFormatRegistry(config = {}) {
+    const configuredFormats = config.rest?.formats ?? {};
+    const keys = new Set([
+        ...Object.keys(BUILT_IN_FORMATS),
+        ...Object.keys(configuredFormats).filter((key) => key !== 'default'),
+    ]);
+    const registry = {};
+    for (const key of keys) {
+        registry[key] = normalizeFormatDefinition(key, configuredFormats[key], BUILT_IN_FORMATS[key]);
+    }
+    return registry;
+}
+export function negotiateRestFormat(config, request, target = 'resource') {
+    const accept = headerValue(request, 'accept');
+    const fallback = defaultFormatKey(config, target);
+    if (!accept) {
+        return fallback;
+    }
+    const preferences = parseAcceptHeader(accept);
+    if (preferences.length === 0) {
+        return fallback;
+    }
+    const registry = normalizeRestFormatRegistry(config);
+    let bestFormat = null;
+    let bestScore = {
+        quality: 0,
+        specificity: -1,
+        index: Number.MAX_SAFE_INTEGER,
+    };
+    for (const [format, definition] of Object.entries(registry)) {
+        if (!rendererForTarget(definition, target)) {
+            continue;
+        }
+        for (const mediaType of definition.mediaTypes ?? []) {
+            const score = acceptedMediaScore(preferences, mediaType);
+            if (compareAcceptScores(score, bestScore) > 0) {
+                bestFormat = format;
+                bestScore = score;
+            }
+        }
+    }
+    return bestScore.quality > 0 ? bestFormat : fallback;
+}
+export function resolveRestFormat(config, format, target = 'resource') {
+    const registry = normalizeRestFormatRegistry(config);
+    const key = format ?? defaultFormatKey(config, target);
+    return resolveRestFormatFromRegistry(config, registry, key, target);
+}
+export function availableRestFormats(config = {}, target = null) {
+    const registry = normalizeRestFormatRegistry(config);
+    return Object.keys(registry)
+        .filter((format) => !target || resolveRestFormat(config, format, target)?.renderer)
+        .sort();
+}
+export function restFormatMetadata(config = {}, routes = {}) {
+    const registry = normalizeRestFormatRegistry(config);
+    return Object.fromEntries(availableRestFormats(config).map((format) => {
+        const definition = registry[format];
+        return [format, {
+                extension: `.${format}`,
+                mediaTypes: definition.mediaTypes ?? [],
+                contentType: definition.contentType ?? contentTypeForMediaTypes(definition.mediaTypes),
+                manifestPath: manifestPathForFormat(routes, format),
+            }];
+    }));
+}
+export function manifestPathForFormat(routes = {}, format) {
+    if (format === 'json' && routes.manifestJsonPath) {
+        return routes.manifestJsonPath;
+    }
+    if (format === 'html' && routes.manifestHtmlPath) {
+        return routes.manifestHtmlPath;
+    }
+    if (format === 'md' && routes.manifestMarkdownPath) {
+        return routes.manifestMarkdownPath;
+    }
+    return `${routes.manifestPath ?? '/__db/manifest'}.${format}`;
+}
+export function renderMarkdownJson(title, value, metadata = []) {
+    return [
+        `# ${title}`,
+        '',
+        ...metadata.map(([label, detail]) => `- ${label}: \`${escapeMarkdownInline(detail)}\``),
+        '',
+        '```json',
+        JSON.stringify(value, null, 2),
+        '```',
+        '',
+    ].join('\n');
+}
+function normalizeFormatDefinition(key, configured, fallback) {
+    const base = fallback ?? {
+        mediaTypes: [],
+    };
+    if (typeof configured === 'string') {
+        return {
+            key,
+            alias: configured,
+            mediaTypes: normalizeMediaTypes(base.mediaTypes),
+            contentType: base.contentType ?? contentTypeForMediaTypes(base.mediaTypes),
+        };
+    }
+    if (typeof configured === 'function') {
+        return {
+            key,
+            mediaTypes: normalizeMediaTypes(base.mediaTypes),
+            contentType: base.contentType ?? contentTypeForMediaTypes(base.mediaTypes),
+            renderResource: configured,
+            renderManifest: base.renderManifest,
+        };
+    }
+    if (isFormatObject(configured)) {
+        const mediaTypes = normalizeMediaTypes(configured.mediaTypes ?? base.mediaTypes);
+        const genericRenderer = typeof configured.render === 'function'
+            ? configured.render
+            : null;
+        return {
+            key,
+            mediaTypes,
+            contentType: configured.contentType ?? base.contentType ?? contentTypeForMediaTypes(mediaTypes),
+            renderResource: typeof configured.renderResource === 'function'
+                ? configured.renderResource
+                : genericRenderer ?? base.renderResource,
+            renderManifest: typeof configured.renderManifest === 'function'
+                ? configured.renderManifest
+                : genericRenderer ?? base.renderManifest,
+        };
+    }
+    return {
+        key,
+        mediaTypes: normalizeMediaTypes(base.mediaTypes),
+        contentType: base.contentType ?? contentTypeForMediaTypes(base.mediaTypes),
+        renderResource: base.renderResource,
+        renderManifest: base.renderManifest,
+    };
+}
+function resolveRestFormatFromRegistry(config, registry, key, target, seen = new Set()) {
+    const normalizedKey = normalizeFormatKey(key);
+    if (!normalizedKey) {
+        return null;
+    }
+    if (seen.has(normalizedKey)) {
+        return null;
+    }
+    seen.add(normalizedKey);
+    if (normalizedKey === 'default') {
+        const configured = config.rest?.formats?.default;
+        if (typeof configured === 'string') {
+            return resolveRestFormatFromRegistry(config, registry, configured, target, seen);
+        }
+        if (typeof configured === 'function') {
+            return target === 'resource'
+                ? {
+                    key: 'default',
+                    contentType: 'text/plain; charset=utf-8',
+                    renderer: configured,
+                }
+                : resolveRestFormatFromRegistry(config, registry, 'json', target, seen);
+        }
+        if (isFormatObject(configured)) {
+            const definition = normalizeFormatDefinition('default', configured, null);
+            const renderer = rendererForTarget(definition, target);
+            if (renderer) {
+                return {
+                    key: 'default',
+                    contentType: definition.contentType,
+                    renderer,
+                };
+            }
+        }
+        return resolveRestFormatFromRegistry(config, registry, 'json', target, seen);
+    }
+    const definition = registry[normalizedKey];
+    if (!definition) {
+        return null;
+    }
+    if (definition.alias) {
+        return resolveRestFormatFromRegistry(config, registry, definition.alias, target, seen);
+    }
+    const renderer = rendererForTarget(definition, target);
+    if (!renderer) {
+        return null;
+    }
+    return {
+        key: normalizedKey,
+        contentType: definition.contentType ?? contentTypeForMediaTypes(definition.mediaTypes),
+        renderer,
+    };
+}
+function defaultFormatKey(config, target) {
+    const configured = config.rest?.formats?.default;
+    if (typeof configured === 'string') {
+        return configured;
+    }
+    if (target === 'resource' && (typeof configured === 'function' || configured)) {
+        return 'default';
+    }
+    return 'json';
+}
+function rendererForTarget(definition, target) {
+    return target === 'manifest' ? definition.renderManifest : definition.renderResource;
+}
+function normalizeFormatKey(value) {
+    return String(value ?? '').replace(/^\./, '').trim();
+}
+function normalizeMediaTypes(value) {
+    if (!value) {
+        return [];
+    }
+    const values = Array.isArray(value) ? value : [value];
+    return values
+        .filter((item) => typeof item === 'string' && item.trim())
+        .map((item) => item.trim().toLowerCase());
+}
+function contentTypeForMediaTypes(mediaTypes = []) {
+    return mediaTypes[0] ? `${mediaTypes[0]}; charset=utf-8` : 'text/plain; charset=utf-8';
+}
+function jsonViewerTitle(url) {
+    if (!url?.pathname) {
+        return 'db JSON';
+    }
+    return url.pathname.split('/').filter(Boolean).pop() ?? 'db JSON';
+}
+function escapeMarkdownInline(value) {
+    return String(value).replaceAll('`', '\\`');
+}
+function headerValue(request, name) {
+    if (typeof request.headers?.get === 'function') {
+        return request.headers.get(name);
+    }
+    const value = request.headers?.[name] ?? request.headers?.[name.toLowerCase()];
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    return String(value);
+}
+function parseAcceptHeader(value) {
+    return String(value).split(',').map((entry, index) => {
+        const [mediaRange, ...parameters] = entry.trim().split(';');
+        let quality = 1;
+        for (const parameter of parameters) {
+            const [name, rawValue] = parameter.trim().split('=');
+            if (name?.toLowerCase() === 'q') {
+                const parsed = Number(rawValue);
+                quality = Number.isFinite(parsed) ? Math.min(1, Math.max(0, parsed)) : 0;
+            }
+        }
+        return {
+            index,
+            mediaRange: mediaRange.toLowerCase(),
+            quality,
+        };
+    }).filter((preference) => preference.mediaRange.includes('/'));
+}
+function acceptedMediaScore(preferences, mediaType) {
+    const [wantedType, wantedSubtype] = mediaType.split('/');
+    let best = {
+        quality: 0,
+        specificity: -1,
+        index: Number.MAX_SAFE_INTEGER,
+    };
+    for (const preference of preferences) {
+        const [type, subtype] = preference.mediaRange.split('/');
+        if ((type !== '*' && type !== wantedType) || (subtype !== '*' && subtype !== wantedSubtype)) {
+            continue;
+        }
+        const specificity = Number(type !== '*') + Number(subtype !== '*');
+        const candidate = {
+            quality: preference.quality,
+            specificity,
+            index: preference.index,
+        };
+        if (compareAcceptScores(candidate, best) > 0) {
+            best = candidate;
+        }
+    }
+    return best;
+}
+function compareAcceptScores(left, right) {
+    if (left.quality !== right.quality) {
+        return left.quality - right.quality;
+    }
+    if (left.specificity !== right.specificity) {
+        return left.specificity - right.specificity;
+    }
+    return right.index - left.index;
+}
+function isFormatObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/rest/handler.d.ts

@@ -0,0 +1,111 @@
+import type { IncomingMessage } from 'node:http';
+type RestConfig = {
+    cwd: string;
+    sourceDir: string;
+    stateDir: string;
+    server?: {
+        apiBase?: string;
+        maxBodyBytes?: number;
+        viewerLinks?: unknown[];
+        [key: string]: unknown;
+    };
+    graphql?: {
+        enabled?: boolean;
+        path?: string;
+        [key: string]: unknown;
+    };
+    rest?: {
+        enabled?: boolean;
+        formats?: Record<string, RestFormatInputLike> & {
+            default?: RestFormatInputLike;
+        };
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+type RestRendererLike = (context: Record<string, unknown>) => unknown;
+type RestFormatObjectLike = {
+    mediaTypes?: string | string[];
+    contentType?: string;
+    render?: RestRendererLike;
+    renderResource?: RestRendererLike;
+    renderManifest?: RestRendererLike;
+    [key: string]: unknown;
+};
+type RestFormatInputLike = string | RestRendererLike | RestFormatObjectLike | null | undefined;
+type RestResource = {
+    name: string;
+    kind?: string;
+    routePath?: string;
+    idField?: string;
+    dataPath?: string;
+    schemaPath?: string;
+    seed?: unknown;
+    [key: string]: unknown;
+};
+type RestCollection = {
+    all(): unknown[] | Promise<unknown[]>;
+    get(id: string): unknown | Promise<unknown>;
+    create(body: unknown): unknown | Promise<unknown>;
+    patch(id: string, body: unknown): unknown | Promise<unknown>;
+    delete(id: string): boolean | Promise<boolean>;
+};
+type RestDocument = {
+    all(): unknown | Promise<unknown>;
+    put(body: unknown): unknown | Promise<unknown>;
+    update(body: unknown): unknown | Promise<unknown>;
+};
+type RestDb = {
+    config: RestConfig;
+    resources: Map<string, RestResource>;
+    diagnostics?: unknown[];
+    schemaVersion?: number;
+    collection(name: string): RestCollection;
+    document(name: string): RestDocument;
+    resourceNames(): string[];
+};
+type RestHeaderBag = {
+    get?: (name: string) => string | null;
+    [key: string]: unknown;
+};
+type RestRequest = (IncomingMessage | AsyncIterable<unknown>) & {
+    method?: string;
+    url?: string;
+    headers?: RestHeaderBag;
+};
+type RestRouteOptionsInput = {
+    apiBase?: string;
+    viewerPath?: string;
+    manifestPath?: string;
+    manifestJsonPath?: string;
+    manifestHtmlPath?: string;
+    manifestMarkdownPath?: string;
+    schemaPath?: string;
+    batchPath?: string;
+    importPath?: string;
+    eventsPath?: string;
+    graphqlPath?: string;
+    restBasePath?: string;
+    resourceRoutesEnabled?: boolean;
+    trace?: unknown;
+    traceNested?: boolean;
+    [key: string]: unknown;
+};
+type RestResult = {
+    status: number;
+    headers: Record<string, unknown>;
+    body: unknown;
+};
+type RawBodyOptions = {
+    maxBytes?: number;
+};
+export declare function handleRestRequest(db: unknown, request: RestRequest, response: unknown, url?: URL, options?: RestRouteOptionsInput): Promise<void>;
+export declare function findResourceByRoute(db: RestDb, routeName: string): RestResource | undefined;
+export declare function executeRestBatch(db: RestDb, body: unknown, options?: RestRouteOptionsInput): Promise<Array<RestResult & {
+    index: number;
+}>>;
+export declare function readRawBody(request: unknown, options?: RawBodyOptions): Promise<Buffer>;
+export declare function readJsonBody(request: unknown, options?: RawBodyOptions): Promise<unknown>;
+export declare function sendJson(response: unknown, status: number, body: unknown): void;
+export declare function sendText(response: unknown, status: number, body: unknown, contentType: string): void;
+export {};