@async/db 0.2.0

package/dist/rest/shape.d.ts

@@ -0,0 +1,33 @@
+type RestRecord = Record<string, unknown>;
+type RestField = {
+    computed?: boolean;
+    [key: string]: unknown;
+};
+type RestRelation = {
+    name: string;
+    sourceField: string;
+    targetResource: string;
+    targetField: string;
+    cardinality: string;
+    [key: string]: unknown;
+};
+type RestResource = {
+    name: string;
+    fields?: Record<string, RestField>;
+    relations?: RestRelation[];
+    [key: string]: unknown;
+};
+type RestCollection = {
+    all: () => Promise<RestRecord[]>;
+};
+type RestDb = {
+    resources: Map<string, RestResource>;
+    collection: (resourceName: string) => RestCollection;
+    config?: unknown;
+    [key: string]: unknown;
+};
+type ShapeOptions = {
+    allowPagination?: boolean;
+};
+export declare function shapeCollectionRead(db: RestDb, resource: RestResource, records: RestRecord[], url: URL, options?: ShapeOptions): Promise<RestRecord[]>;
+export {};

package/dist/rest/shape.js

@@ -0,0 +1,218 @@
+import { dbError, listChoices } from '../errors.js';
+import { resolveSelectedComputedFields } from '../features/runtime/fanout.js';
+import { resolveResource } from '../names.js';
+export async function shapeCollectionRead(db, resource, records, url, options = {}) {
+    const query = parseShapeQuery(db, resource, url, options);
+    const paginated = options.allowPagination ? paginateRecords(records, query) : records;
+    const expanded = query.expand.length > 0
+        ? await expandRecords(db, paginated, query)
+        : paginated;
+    if (query.select.length === 0) {
+        return expanded;
+    }
+    const computed = query.select
+        .filter(([head, child]) => !child && resource.fields?.[head]?.computed)
+        .map(([head]) => head);
+    const resolved = computed.length > 0
+        ? await resolveSelectedComputedFields(db, resource, expanded, computed)
+        : expanded;
+    return resolved.map((record) => projectRecord(record, query));
+}
+function parseShapeQuery(db, resource, url, options) {
+    const relationMap = new Map((resource.relations ?? []).map((relation) => [relation.name, relation]));
+    const expand = parseListParam(url.searchParams.get('expand'));
+    const select = parseListParam(url.searchParams.get('select')).map((path) => path.split('.'));
+    for (const relationName of expand) {
+        const relation = relationMap.get(relationName);
+        if (!relation) {
+            throw dbError('REST_EXPAND_UNKNOWN_RELATION', `Unknown expanded relation "${relationName}" on ${resource.name}.`, {
+                status: 400,
+                hint: `Use one of: ${listChoices([...relationMap.keys()])}.`,
+                details: {
+                    resource: resource.name,
+                    relation: relationName,
+                    availableRelations: [...relationMap.keys()],
+                },
+            });
+        }
+        if (relation.cardinality !== 'one') {
+            throw dbError('REST_EXPAND_UNSUPPORTED_CARDINALITY', `Relation "${relationName}" on ${resource.name} cannot be expanded by REST yet because it is ${relation.cardinality}.`, {
+                status: 400,
+                hint: 'MVP REST expansion supports explicit to-one relations only.',
+                details: relation,
+            });
+        }
+    }
+    validateSelectedFields(db, resource, select, new Set(expand), relationMap);
+    const offset = options.allowPagination
+        ? parseOffset(url.searchParams.get('offset'))
+        : 0;
+    const limit = options.allowPagination
+        ? parseLimit(url.searchParams.get('limit'))
+        : undefined;
+    return {
+        select,
+        expand,
+        offset,
+        limit,
+        relationMap,
+    };
+}
+function validateSelectedFields(db, resource, select, expanded, relationMap) {
+    for (const parts of select) {
+        const [head, child, extra] = parts;
+        if (!head || extra !== undefined) {
+            throw dbError('REST_SELECT_UNSUPPORTED_DEPTH', `Selected path "${parts.join('.')}" is too deep.`, {
+                status: 400,
+                hint: 'Use top-level fields or one nested relation field such as "author.name".',
+                details: {
+                    resource: resource.name,
+                    path: parts.join('.'),
+                },
+            });
+        }
+        const relation = relationMap.get(head);
+        if (!child) {
+            if (head in (resource.fields ?? {}) || relation) {
+                if (relation && !expanded.has(head)) {
+                    throw selectRequiresExpand(resource, head);
+                }
+                continue;
+            }
+            throw unknownSelectField(resource, head, availableShapeFields(resource, relationMap));
+        }
+        if (!relation) {
+            throw unknownSelectField(resource, head, availableShapeFields(resource, relationMap));
+        }
+        if (!expanded.has(head)) {
+            throw selectRequiresExpand(resource, head);
+        }
+        const target = resolveResource(db.resources, relation.targetResource).resource;
+        const targetFields = target?.fields ?? {};
+        if (!(child in targetFields)) {
+            throw unknownSelectField(target ?? resource, child, Object.keys(targetFields), `${head}.${child}`);
+        }
+    }
+}
+function unknownSelectField(resource, field, availableFields, path = field) {
+    return dbError('REST_SELECT_UNKNOWN_FIELD', `Unknown selected field "${field}" on ${resource.name}.`, {
+        status: 400,
+        hint: `Use one of: ${listChoices(availableFields)}.`,
+        details: {
+            resource: resource.name,
+            field,
+            path,
+            availableFields: [...availableFields],
+        },
+    });
+}
+function selectRequiresExpand(resource, relationName) {
+    return dbError('REST_SELECT_REQUIRES_EXPAND', `Selected relation "${relationName}" on ${resource.name} requires explicit expand.`, {
+        status: 400,
+        hint: `Add expand=${relationName} to include nested relation fields.`,
+        details: {
+            resource: resource.name,
+            relation: relationName,
+        },
+    });
+}
+function availableShapeFields(resource, relationMap) {
+    return [...new Set([...Object.keys(resource.fields ?? {}), ...relationMap.keys()])];
+}
+function paginateRecords(records, query) {
+    const end = query.limit === undefined ? undefined : query.offset + query.limit;
+    return records.slice(query.offset, end);
+}
+async function expandRecords(db, records, query) {
+    const nextRecords = records.map((record) => ({ ...record }));
+    for (const relationName of query.expand) {
+        const relation = query.relationMap.get(relationName);
+        const targets = await db.collection(relation.targetResource).all();
+        const targetById = new Map();
+        for (const target of targets) {
+            const targetValue = target?.[relation.targetField];
+            if (targetValue === undefined || targetValue === null) {
+                continue;
+            }
+            const key = String(targetValue);
+            if (!targetById.has(key)) {
+                targetById.set(key, target);
+            }
+        }
+        for (const record of nextRecords) {
+            const value = record?.[relation.sourceField];
+            if (value === undefined || value === null || value === '') {
+                record[relation.name] = null;
+                continue;
+            }
+            record[relation.name] = targetById.get(String(value)) ?? null;
+        }
+    }
+    return nextRecords;
+}
+function projectRecord(record, query) {
+    const projected = {};
+    for (const [head, child] of query.select) {
+        if (!child) {
+            if (record?.[head] !== undefined) {
+                projected[head] = record[head];
+            }
+            continue;
+        }
+        if (record?.[head] === null) {
+            projected[head] = null;
+            continue;
+        }
+        const nested = record?.[head];
+        if (!isRecord(nested)) {
+            continue;
+        }
+        if (!isRecord(projected[head])) {
+            projected[head] = {};
+        }
+        const projectedNested = projected[head];
+        if (nested[child] !== undefined) {
+            projectedNested[child] = nested[child];
+        }
+    }
+    return projected;
+}
+function parseListParam(value) {
+    return String(value ?? '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter((item) => item !== '');
+}
+function parseOffset(value) {
+    if (value === null || value === undefined || value === '') {
+        return 0;
+    }
+    if (!/^\d+$/.test(value)) {
+        throw dbError('REST_INVALID_OFFSET', `REST offset must be a non-negative integer: ${value}`, {
+            status: 400,
+            hint: 'Use offset=0, offset=20, or omit offset.',
+            details: {
+                offset: value,
+            },
+        });
+    }
+    return Number(value);
+}
+function parseLimit(value) {
+    if (value === null || value === undefined || value === '') {
+        return undefined;
+    }
+    if (!/^\d+$/.test(value) || Number(value) <= 0) {
+        throw dbError('REST_INVALID_LIMIT', `REST limit must be a positive integer: ${value}`, {
+            status: 400,
+            hint: 'Use limit=20, limit=100, or omit limit.',
+            details: {
+                limit: value,
+            },
+        });
+    }
+    return Number(value);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/schema-builders.d.ts

@@ -0,0 +1 @@
+export { collection, document, field, files } from './features/schema/builders.js';

package/dist/schema-builders.js

@@ -0,0 +1 @@
+export { collection, document, field, files } from './features/schema/builders.js';

package/dist/schema-manifest.d.ts

@@ -0,0 +1 @@
+export { generateSchemaManifest, renderSchemaManifest } from './features/schema/manifest.js';

package/dist/schema-manifest.js

@@ -0,0 +1 @@
+export { generateSchemaManifest, renderSchemaManifest } from './features/schema/manifest.js';

package/dist/schema.d.ts

@@ -0,0 +1,193 @@
+export type FieldDefinition =
+  | ({ type: 'string' } & FieldOptions<string>)
+  | ({ type: 'datetime' } & FieldOptions<string>)
+  | ({ type: 'number' } & FieldOptions<number>)
+  | ({ type: 'boolean' } & FieldOptions<boolean>)
+  | ({ type: 'enum'; values: readonly (string | number | boolean)[] } & FieldOptions<string | number | boolean>)
+  | ({ type: 'object'; fields?: Record<string, FieldDefinition>; additionalProperties?: boolean } & FieldOptions<Record<string, unknown>>)
+  | ({ type: 'array'; items?: FieldDefinition } & FieldOptions<unknown[]>)
+  | ({ type: 'unknown' } & FieldOptions<unknown>);
+
+export type FieldOptions<DefaultValue> = {
+  required?: boolean;
+  nullable?: boolean;
+  description?: string;
+  default?: DefaultValue;
+  computed?: boolean;
+  readOnly?: boolean;
+  relation?: RelationDefinition;
+  unique?: boolean;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+};
+
+export type FieldMetaOptions = FieldOptions<unknown> & {
+  type?: FieldDefinition['type'];
+  values?: readonly (string | number | boolean)[];
+  fields?: Record<string, FieldDefinition>;
+  items?: FieldDefinition;
+  additionalProperties?: boolean;
+  [key: string]: unknown;
+};
+
+export type RelationDefinition = {
+  /** Output name used by REST expand, such as "author" for authorId. */
+  name?: string;
+  /** Target collection resource name. */
+  to: string;
+  /** Target collection field. Defaults to "id". */
+  toField?: string;
+  /** MVP supports explicit to-one expansion. */
+  cardinality?: 'one' | 'many';
+};
+
+export type ObjectFieldOptions = FieldOptions<Record<string, unknown>> & {
+  additionalProperties?: boolean;
+};
+
+export type ResourceDefinition = {
+  description?: string;
+  idField?: string;
+  source?: FilesSourceDefinition | string | readonly string[];
+  fields: Record<string, FieldDefinition>;
+  seed?: unknown;
+};
+
+export type StandardSchemaIssue = {
+  message?: string;
+  path?: readonly unknown[];
+  [key: string]: unknown;
+};
+
+export type StandardSchemaResult<Value = unknown> = {
+  value?: Value;
+  issues?: readonly StandardSchemaIssue[];
+};
+
+export type StandardSchemaV1<Input = unknown, Output = unknown> = {
+  '~standard': {
+    version: 1;
+    vendor?: string;
+    validate(value: Input): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    jsonSchema?: {
+      output?: (options?: Record<string, unknown>) => unknown;
+    };
+    [key: string]: unknown;
+  };
+};
+
+export type StandardSchemaResourceOptions = Omit<ResourceDefinition, 'fields'> & {
+  fields?: Record<string, FieldDefinition>;
+};
+
+export type StandardSchemaMixedResourceDefinition<Input = unknown, Output = unknown> =
+  StandardSchemaResourceOptions & {
+    /** Preferred object-first validator hook. */
+    validator: StandardSchemaV1<Input, Output>;
+    /** Compatibility alias for older examples. Prefer validator. */
+    standardSchema?: StandardSchemaV1<Input, Output>;
+  };
+
+export type StandardSchemaLegacyMixedResourceDefinition<Input = unknown, Output = unknown> =
+  StandardSchemaResourceOptions & {
+    /** Compatibility alias. Prefer validator. */
+    standardSchema: StandardSchemaV1<Input, Output>;
+  };
+
+export type FilesSourceDefinition = {
+  kind: 'files';
+  patterns: readonly string[];
+  read?: 'frontmatter' | 'json' | 'jsonc' | 'text' | string;
+};
+
+export type ComputedResolverThis = {
+  get(key: string): unknown;
+  has(key: string): boolean;
+  value: unknown;
+  record: unknown;
+  records: unknown[] | undefined;
+  args: unknown;
+  db: unknown;
+  resource: ResourceDefinition & { kind?: 'collection' | 'document' };
+  field: FieldDefinition | undefined;
+  fieldName: string | undefined;
+  config: unknown;
+  services: Record<string, unknown>;
+  cache: Map<string, unknown>;
+  _internal: {
+    get(key: string): unknown;
+    has(key: string): boolean;
+    value: unknown;
+    record: unknown;
+    records: unknown[] | undefined;
+    args: unknown;
+    db: unknown;
+    resource: ResourceDefinition & { kind?: 'collection' | 'document' };
+    field: FieldDefinition | undefined;
+    fieldName: string | undefined;
+    config: unknown;
+    services: Record<string, unknown>;
+    cache: Map<string, unknown>;
+  };
+};
+
+export type ComputedFieldResolver<RecordValue = Record<string, unknown>, Value = unknown> = {
+  resolve?: (this: ComputedResolverThis, context: {
+    record: RecordValue;
+    db: unknown;
+    resource: ResourceDefinition & { kind?: 'collection' | 'document' };
+    cache: Map<string, unknown>;
+    [key: string]: unknown;
+  }) => Value | Promise<Value>;
+  resolveMany?: (this: ComputedResolverThis, context: {
+    records: RecordValue[];
+    db: unknown;
+    resource: ResourceDefinition & { kind?: 'collection' | 'document' };
+    cache: Map<string, unknown>;
+    [key: string]: unknown;
+  }) => Map<string | number, Value> | Value[] | Record<string, Value> | Promise<Map<string | number, Value> | Value[] | Record<string, Value>>;
+};
+
+export function collection(definition: ResourceDefinition): ResourceDefinition & { kind: 'collection' };
+export function collection<Input = unknown, Output = unknown>(
+  definition: StandardSchemaMixedResourceDefinition<Input, Output>,
+): StandardSchemaMixedResourceDefinition<Input, Output> & { kind: 'collection' };
+export function collection<Input = unknown, Output = unknown>(
+  definition: StandardSchemaLegacyMixedResourceDefinition<Input, Output>,
+): StandardSchemaLegacyMixedResourceDefinition<Input, Output> & { kind: 'collection' };
+export function collection<Input = unknown, Output = unknown>(
+  definition: StandardSchemaV1<Input, Output>,
+  options?: StandardSchemaResourceOptions,
+): StandardSchemaResourceOptions & { kind: 'collection'; validator: StandardSchemaV1<Input, Output> };
+export function document(definition: ResourceDefinition): ResourceDefinition & { kind: 'document' };
+export function document<Input = unknown, Output = unknown>(
+  definition: StandardSchemaMixedResourceDefinition<Input, Output>,
+): StandardSchemaMixedResourceDefinition<Input, Output> & { kind: 'document' };
+export function document<Input = unknown, Output = unknown>(
+  definition: StandardSchemaLegacyMixedResourceDefinition<Input, Output>,
+): StandardSchemaLegacyMixedResourceDefinition<Input, Output> & { kind: 'document' };
+export function document<Input = unknown, Output = unknown>(
+  definition: StandardSchemaV1<Input, Output>,
+  options?: StandardSchemaResourceOptions,
+): StandardSchemaResourceOptions & { kind: 'document'; validator: StandardSchemaV1<Input, Output> };
+export function files(patterns: string | readonly string[], options?: { read?: FilesSourceDefinition['read'] }): FilesSourceDefinition;
+
+export const field: {
+  string(options?: FieldOptions<string>): FieldDefinition;
+  datetime(options?: FieldOptions<string>): FieldDefinition;
+  number(options?: FieldOptions<number>): FieldDefinition;
+  boolean(options?: FieldOptions<boolean>): FieldDefinition;
+  enum<const Values extends readonly (string | number | boolean)[]>(
+    values: Values,
+    options?: FieldOptions<Values[number]>,
+  ): FieldDefinition;
+  object(fields?: Record<string, FieldDefinition>, options?: ObjectFieldOptions): FieldDefinition;
+  array(items?: FieldDefinition, options?: FieldOptions<unknown[]>): FieldDefinition;
+  json(options?: FieldOptions<unknown>): FieldDefinition;
+  meta(options?: FieldMetaOptions): FieldDefinition;
+  nullable(definition: FieldDefinition, options?: Omit<FieldOptions<unknown>, 'nullable'>): FieldDefinition;
+  computed(definition: FieldDefinition, resolver?: ComputedFieldResolver['resolve'] | ComputedFieldResolver): FieldDefinition;
+};

package/dist/schema.js

@@ -0,0 +1,6 @@
+export { loadProjectSchema } from './features/schema/project.js';
+export { createDbSchema, createSchemaValidator, loadDbSchema } from './features/schema/api.js';
+export { makeGeneratedSchema } from './features/schema/generated.js';
+export { inferFieldFromSamples, inferFieldFromValue, inferFieldsFromData, normalizeField } from './features/schema/fields.js';
+export { normalizeSchemaLoadMode, resolveSchemaLocator } from './features/schema/locator.js';
+export { assertRecordMatchesResource, uniqueDuplicateDiagnostic, validateRecordAgainstResource, validateUniqueCollectionFields, validateValueAgainstField } from './features/schema/validation.js';

package/dist/server.d.ts

@@ -0,0 +1,116 @@
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { watch } from 'node:fs';
+type ServerTraceConfig = boolean | {
+    enabled?: boolean;
+    slowMs?: number;
+    console?: boolean;
+    events?: boolean;
+    header?: string;
+} | null;
+type ServerConfig = {
+    cwd?: string;
+    sourceDir?: string;
+    stateDir?: string;
+    server?: {
+        host?: string;
+        port?: number | string;
+        apiBase?: string;
+        dataPath?: string | false | null;
+        maxBodyBytes?: number;
+        trace?: ServerTraceConfig;
+        expose?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    graphql?: {
+        enabled?: boolean;
+        path?: string;
+        [key: string]: unknown;
+    };
+    rest?: {
+        enabled?: boolean;
+        [key: string]: unknown;
+    };
+    operations?: {
+        sourceDir?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+type ServerResource = {
+    name: string;
+    kind?: string;
+    routePath?: string;
+    [key: string]: unknown;
+};
+type ServerDb = {
+    config: ServerConfig;
+    resources: Map<string, ServerResource>;
+    diagnostics?: unknown[];
+    schemaVersion?: number;
+    close?: () => unknown | Promise<unknown>;
+};
+type StartServerOptions = Record<string, unknown> & {
+    host?: string;
+    port?: string | number;
+};
+type RequestRoutesOptions = Record<string, unknown> & {
+    apiBase?: string;
+    rootRoutes?: boolean;
+    restBasePath?: string | null;
+    dataPath?: string | false | null;
+    graphqlPath?: string;
+    manifestPath?: string;
+    manifestJsonPath?: string;
+    manifestHtmlPath?: string;
+    manifestMarkdownPath?: string;
+};
+type RequestHandlerOptions = RequestRoutesOptions & {
+    events?: ViewerEventHub;
+    trace?: ServerTraceConfig;
+};
+type DbRequestHandler = (request: IncomingMessage, response: ServerResponse, next?: () => unknown) => Promise<boolean>;
+type ViewerEventPayload = Record<string, unknown> & {
+    type: string;
+    version?: number;
+    diagnostics?: unknown[];
+};
+type ViewerEventHub = {
+    subscribe(request: IncomingMessage, response: ServerResponse, db: ServerDb): void;
+    publish(payload: ViewerEventPayload): void;
+    close(): void;
+};
+type WatchSourceOptions = {
+    watch?: typeof watch;
+    warn?: (message: string) => unknown;
+};
+type SourceWatcher = {
+    readonly enabled: boolean;
+    close(): void;
+};
+export declare function startDbServer(options?: StartServerOptions): Promise<{
+    server: Server;
+    db: ServerDb;
+    url: string;
+}>;
+export declare function createDbRequestHandler(db: ServerDb, options?: RequestHandlerOptions): DbRequestHandler;
+export declare function reloadDb(db: ServerDb): Promise<{
+    [key: string]: unknown;
+    resources: {
+        [key: string]: unknown;
+        name: string;
+        schemaPath?: string | null;
+        dataPath?: string | null;
+    }[];
+    diagnostics: {
+        [key: string]: unknown;
+        code?: string;
+        severity?: string;
+        message: string;
+    }[];
+    schema?: Record<string, unknown>;
+} & {
+    logs: string[];
+}>;
+export declare function watchSourceDir(db: ServerDb, events: ViewerEventHub, options?: WatchSourceOptions): Promise<SourceWatcher>;
+export declare function createViewerEventHub(): ViewerEventHub;
+export {};