@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/search.d.ts

@@ -0,0 +1,16 @@
+import type { PrototypeRuntime } from '@protoyard/core';
+import type { Blueprint } from './schema.ts';
+export interface EntitySearchMatch {
+    entityName: string;
+    entityLabel: string;
+    recordId: string;
+    title: string;
+    matchedFields: string[];
+    titleMatch: boolean;
+}
+export interface SearchEntitiesOptions {
+    /** Maximum number of results returned for each readable entity. Defaults to 10. */
+    limitPerEntity?: number;
+}
+/** Searches every readable entity using its title field and declared searchable fields. */
+export declare function searchEntities(runtime: PrototypeRuntime, blueprint: Blueprint, query: string, options?: SearchEntitiesOptions): Promise<EntitySearchMatch[]>;

package/dist/search.js

@@ -0,0 +1,96 @@
+import { createEntityServices } from "./services.js";
+import { inputProperty } from "./validation.js";
+function normalize(value) {
+    return value.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase();
+}
+function searchableText(value) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value
+            .filter((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')
+            .map(String)
+            .join(' ');
+    }
+    return '';
+}
+function entityLabel(entity) {
+    return (entity.label ??
+        entity.name.replace(/-/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase()));
+}
+function fieldMap(entity) {
+    return new Map(entity.fields.map((field) => [field.name, field]));
+}
+function compareMatches(left, right) {
+    return (Number(right.titleMatch) - Number(left.titleMatch) ||
+        Number(right.exactTitleMatch) - Number(left.exactTitleMatch) ||
+        Number(right.titlePrefixMatch) - Number(left.titlePrefixMatch) ||
+        (left.entityName < right.entityName ? -1 : left.entityName > right.entityName ? 1 : 0) ||
+        (left.normalizedTitle < right.normalizedTitle
+            ? -1
+            : left.normalizedTitle > right.normalizedTitle
+                ? 1
+                : 0) ||
+        (left.recordId < right.recordId ? -1 : left.recordId > right.recordId ? 1 : 0));
+}
+/** Searches every readable entity using its title field and declared searchable fields. */
+export async function searchEntities(runtime, blueprint, query, options = {}) {
+    const normalizedQuery = normalize(query.trim());
+    if (!normalizedQuery)
+        return [];
+    const requestedLimit = options.limitPerEntity ?? 10;
+    const limitPerEntity = Number.isFinite(requestedLimit)
+        ? Math.max(0, Math.floor(requestedLimit))
+        : 10;
+    if (limitPerEntity === 0)
+        return [];
+    const services = createEntityServices(runtime, blueprint);
+    const entityMatches = await Promise.all(blueprint.entities.map(async (entity) => {
+        const capability = `${entity.name}:read`;
+        if (!runtime.session.can(capability))
+            return [];
+        const service = services[entity.name];
+        if (!service)
+            return [];
+        const rows = await service.list();
+        const hasRecordReadRule = Boolean(runtime.policy.definition.rules?.[capability]);
+        const fields = fieldMap(entity);
+        const searchableNames = [...new Set([entity.titleField, ...entity.searchable])];
+        const titleField = fields.get(entity.titleField);
+        const matches = [];
+        for (const row of rows) {
+            if (hasRecordReadRule && !runtime.session.can(capability, row))
+                continue;
+            const title = searchableText(titleField ? row[inputProperty(titleField)] : '').trim();
+            const normalizedTitle = normalize(title);
+            const matchedFields = [];
+            for (const fieldName of searchableNames) {
+                const field = fields.get(fieldName);
+                if (!field)
+                    continue;
+                const value = normalize(searchableText(row[inputProperty(field)]));
+                if (value.includes(normalizedQuery))
+                    matchedFields.push(fieldName);
+            }
+            if (matchedFields.length === 0)
+                continue;
+            matches.push({
+                entityName: entity.name,
+                entityLabel: entityLabel(entity),
+                recordId: row.id,
+                title: title || row.id,
+                matchedFields,
+                titleMatch: matchedFields.includes(entity.titleField),
+                normalizedTitle,
+                exactTitleMatch: normalizedTitle === normalizedQuery,
+                titlePrefixMatch: normalizedTitle.startsWith(normalizedQuery),
+            });
+        }
+        return matches.sort(compareMatches).slice(0, limitPerEntity);
+    }));
+    return entityMatches
+        .flat()
+        .sort(compareMatches)
+        .map(({ normalizedTitle: _normalizedTitle, exactTitleMatch: _exactTitleMatch, titlePrefixMatch: _titlePrefixMatch, ...match }) => match);
+}

package/dist/services.d.ts

@@ -0,0 +1,89 @@
+import { type PrototypeRuntime, type Row } from '@protoyard/core';
+import { type CsvParseOptions, type CsvSerializeOptions, type CsvValidationResult } from './csv.ts';
+import { type Blueprint, type BlueprintEntity } from './schema.ts';
+import { type EntityInput } from './validation.ts';
+/** Thrown when a record does not exist (or was removed meanwhile). */
+export declare class EntityNotFoundError extends Error {
+    readonly code: "not-found";
+    constructor(entity: string, id: string);
+}
+/** Thrown when `onDelete: 'restrict'` blocks a removal; nothing was deleted. */
+export declare class EntityInUseError extends Error {
+    readonly code: "in-use";
+    constructor(entity: string, references: Record<string, number>);
+}
+export interface EntityService {
+    readonly entity: BlueprintEntity;
+    readonly table: string;
+    /** Rows sorted by `defaultSort` (else `createdAt`); soft-deleted rows are hidden. */
+    list(): Promise<Row[]>;
+    /** Soft-deleted rows sorted by the entity default sort; empty when soft delete is disabled. */
+    trash(): Promise<Row[]>;
+    get(id: string): Promise<Row | undefined>;
+    create(input: EntityInput): Promise<Row>;
+    update(id: string, patch: EntityInput): Promise<Row>;
+    /** Returns an undo token for soft-delete entities; hard-delete entities return undefined. */
+    remove(id: string): Promise<string | undefined>;
+    /** Restores the complete row set affected by a soft remove before its simulated deadline. */
+    restore(undoToken: string): Promise<number>;
+    /** Restores a trashed row and the soft-delete cascade recorded for it. */
+    restoreTrashed(id: string): Promise<number>;
+    /** Permanently removes a trashed row and its cascade dependents. */
+    purge(id: string): Promise<number>;
+    /**
+     * Gives the record the next face for one avatar field (default: the first)
+     * and returns the saved row. Same contract as `update` (`<entity>:update` or
+     * `update:own`, operation `<entity>.shuffleAvatar`). Deterministic: the next
+     * face depends only on the record id, the field and the current face (see
+     * `nextAvatar`), so repeated shuffles visit every face before any repeats.
+     */
+    shuffleAvatar(id: string, field?: string): Promise<Row>;
+    bulkUpdate(ids: readonly string[], patch: EntityInput): Promise<Row[]>;
+    /** Removes every id (with `onDelete` effects) and returns how many rows were deleted. */
+    bulkRemove(ids: readonly string[]): Promise<number>;
+    /**
+     * Visible rows as CSV text (headers = field labels). Gated by `<entity>:export`.
+     * Optional filter narrows the listed set; relation cells are the stored ids.
+     */
+    exportCsv(filter?: ExportCsvFilter, options?: CsvSerializeOptions): Promise<string>;
+    /**
+     * CSV import: `mode: 'preview'` (default) validates only; `mode: 'commit'` writes
+     * in one transaction (chunks of {@link BULK_CHUNK}). Gated by `<entity>:import`.
+     * Relation cells accept a target id or its title. Without `skipInvalid`, any
+     * invalid row aborts the commit and writes nothing.
+     */
+    importCsv(text: string, options?: ImportCsvOptions): Promise<ImportCsvResult>;
+}
+/** Optional narrow of `list()` before export. */
+export interface ExportCsvFilter {
+    ids?: readonly string[];
+    where?: (row: Row) => boolean;
+}
+export interface ImportCsvOptions extends CsvParseOptions {
+    /** `preview` validates only; `commit` writes (default `preview`). */
+    mode?: 'preview' | 'commit';
+    /**
+     * On commit: write only valid rows when true; when false (default), any
+     * invalid row fails the whole import and nothing is written.
+     */
+    skipInvalid?: boolean;
+    serialize?: CsvSerializeOptions;
+}
+export interface ImportCsvResult extends CsvValidationResult {
+    mode: 'preview' | 'commit';
+    /** Rows written on a successful commit (empty on preview). */
+    created: Row[];
+    /** Audit entry ids written for this batch (when `features.audit` is on). */
+    auditIds: string[];
+}
+/** Thrown when commit is requested and invalid rows remain without `skipInvalid`. */
+export declare class ImportCsvError extends Error {
+    readonly code: "import-invalid";
+    readonly report: ImportCsvResult;
+    constructor(report: ImportCsvResult);
+}
+export type EntityServices = Record<string, EntityService>;
+/** Writes larger than this go through several `bulkPut` calls inside the same transaction. */
+export declare const BULK_CHUNK = 1000;
+export declare const UNDO_WINDOW_MS = 30000;
+export declare function createEntityServices(runtime: PrototypeRuntime, blueprint: Blueprint): EntityServices;