@adecore/editor 0.22.1 → 0.23.0

package/src/search-client.ts

@@ -0,0 +1,306 @@
+import { createWorkerRequestClient, WorkerRequestError } from './worker-client.ts';
+import type { FindMatch } from '@adecore/editor-core';
+import type { EditorFindQuery } from './types.ts';
+import {
+    SEARCH_LIMIT,
+    MAX_REPLACEMENT_PAGE,
+    MAX_REPLACEMENT_CHARACTERS,
+    type EditorSearchRange,
+    type EditorSearchNextOptions,
+    type EditorSearchReplacementOptions,
+    type EditorSearchReplacements,
+    type EditorSearchInput,
+    type EditorSearchOptions,
+    type EditorSearchOutput,
+    type EditorSearchResult,
+    type EditorSearchSnapshot
+} from './search-protocol.ts';
+
+export type EditorSearchErrorKind = 'timeout' | 'superseded' | 'unavailable' | 'syntax' | 'range' | 'snapshot' | 'error' | 'disposed';
+
+export class EditorSearchError extends Error {
+    readonly kind: EditorSearchErrorKind;
+
+    constructor(kind: EditorSearchErrorKind, message: string) {
+        super(message);
+        this.name = 'EditorSearchError';
+        this.kind = kind;
+    }
+}
+
+export interface EditorSearchClientOptions {
+    readonly workerFactory: () => Pick<Worker, 'addEventListener' | 'removeEventListener' | 'postMessage' | 'terminate'>;
+    /* Milliseconds, starting when the request is posted, including worker startup. Defaults to 1,500. */
+    readonly deadline?: number;
+    readonly schedule?: (callback: () => void, delay: number) => () => void;
+}
+
+export interface EditorSearchClient {
+    /* One document per client; a revision must identify the same immutable text for its lifetime. */
+    search(snapshot: EditorSearchSnapshot, query: EditorFindQuery, options?: EditorSearchOptions): Promise<EditorSearchResult>;
+    match(
+        snapshot: EditorSearchSnapshot,
+        query: EditorFindQuery,
+        range: { readonly from: number; readonly to: number; readonly deadline?: number }
+    ): Promise<FindMatch | null>;
+    next(snapshot: EditorSearchSnapshot, query: EditorFindQuery, offset: number, options?: EditorSearchNextOptions): Promise<EditorSearchRange | null>;
+    replacements(
+        snapshot: EditorSearchSnapshot,
+        query: EditorFindQuery,
+        replacement: string,
+        options?: EditorSearchReplacementOptions
+    ): Promise<EditorSearchReplacements>;
+    cancel(): void;
+    /* Frees the snapshot and worker; this client can start again afterward. */
+    release(): void;
+    dispose(): void;
+}
+
+type SearchReply = Exclude<EditorSearchOutput, { type: 'ready' | 'error' }>;
+
+function validateSearch(snapshot: EditorSearchSnapshot, query: EditorFindQuery, options: EditorSearchOptions): void {
+    const from = options.from ?? 0;
+    const to = options.to ?? snapshot.text.length;
+    const maximum = options.maxResults ?? SEARCH_LIMIT;
+    if (
+        !Number.isSafeInteger(snapshot.revision) ||
+        snapshot.revision < 0 ||
+        !Number.isInteger(from) ||
+        !Number.isInteger(to) ||
+        from < 0 ||
+        to < from ||
+        to > snapshot.text.length
+    ) {
+        throw new EditorSearchError('range', 'Search bounds and revision must identify the current document.');
+    }
+    if (!Number.isInteger(maximum) || maximum < 0 || maximum > SEARCH_LIMIT) {
+        throw new EditorSearchError('range', `Search results must be limited to ${SEARCH_LIMIT} matches or fewer.`);
+    }
+    if (options.deadline !== undefined && (!Number.isFinite(options.deadline) || options.deadline <= 0 || options.deadline > 2147483647)) {
+        throw new EditorSearchError('range', 'A request deadline must fit a positive browser timer.');
+    }
+    if (query.regex) {
+        try {
+            // Compilation reports syntax errors without executing the expression on the page.
+            new RegExp(query.text, `gmu${query.caseSensitive ? '' : 'i'}`);
+        } catch (error) {
+            throw new EditorSearchError('syntax', error instanceof Error ? error.message : String(error));
+        }
+    }
+}
+
+function splitsSurrogate(text: string, offset: number): boolean {
+    const previous = text.charCodeAt(offset - 1),
+        current = text.charCodeAt(offset);
+    return previous >= 0xd800 && previous <= 0xdbff && current >= 0xdc00 && current <= 0xdfff;
+}
+
+export function createSearchClient(options: EditorSearchClientOptions): EditorSearchClient {
+    let revision: number | undefined;
+    const transport = createWorkerRequestClient<EditorSearchInput, Exclude<EditorSearchOutput, { type: 'ready' }>>({
+        ...options,
+        accepts: (reply, input) => reply.revision === input.revision,
+        failure: (reply) =>
+            reply.type === 'error'
+                ? { error: new EditorSearchError(reply.kind, reply.message), restart: reply.kind !== 'syntax' && reply.kind !== 'range' }
+                : undefined,
+        prepare: (input) => {
+            const { text, ...rest } = input;
+            const message = { ...rest, ...(revision !== input.revision ? { text } : {}) };
+            revision = input.revision;
+            return message;
+        },
+        stopped: () => {
+            revision = undefined;
+        }
+    });
+    const run = <Result>(
+        snapshot: EditorSearchSnapshot,
+        query: EditorFindQuery,
+        bounds: EditorSearchOptions,
+        input: (id: number) => EditorSearchInput,
+        read: (reply: SearchReply) => Result,
+        validate?: () => void
+    ): Promise<Result> => {
+        return transport
+            .request(input, bounds.deadline, () => {
+                validateSearch(snapshot, query, bounds);
+                validate?.();
+            })
+            .then((reply) => {
+                if (reply.type === 'error') {
+                    throw new EditorSearchError(reply.kind, reply.message);
+                }
+                return read(reply);
+            })
+            .catch((error) => {
+                throw error instanceof WorkerRequestError
+                    ? new EditorSearchError(error.kind, error.message)
+                    : error instanceof EditorSearchError
+                      ? error
+                      : new EditorSearchError('error', error instanceof Error ? error.message : String(error));
+            });
+    };
+    return {
+        search(snapshot, query, bounds = {}) {
+            return run(
+                snapshot,
+                query,
+                bounds,
+                (id) => ({
+                    type: 'search',
+                    id,
+                    revision: snapshot.revision,
+                    text: snapshot.text,
+                    query: { ...query },
+                    ...bounds,
+                    maxResults: bounds.maxResults ?? SEARCH_LIMIT
+                }),
+                (reply) => {
+                    if (reply.type !== 'matches') {
+                        throw new EditorSearchError('error', 'The worker returned an unexpected search response.');
+                    }
+                    return { revision: reply.revision, ranges: reply.ranges, limited: reply.limited };
+                }
+            );
+        },
+        match(snapshot, query, range) {
+            const from = range.from,
+                to = range.to;
+            const text = snapshot.text;
+            return run(
+                snapshot,
+                query,
+                { from, to, maxResults: 1, deadline: range.deadline },
+                (id) => ({ type: 'match', id, revision: snapshot.revision, text, query: { ...query }, from, to }),
+                (reply) => {
+                    if (reply.type !== 'match') {
+                        throw new EditorSearchError('error', 'The worker returned an unexpected match response.');
+                    }
+                    if (reply.match === null) {
+                        return null;
+                    }
+                    if (reply.match.from !== from || reply.match.to !== to) {
+                        throw new EditorSearchError('error', 'The worker returned a different match range.');
+                    }
+                    return { ...reply.match, text: text.slice(from, to), revision: reply.revision };
+                }
+            );
+        },
+        next(snapshot, query, offset, bounds = {}) {
+            return run(
+                snapshot,
+                query,
+                { from: bounds.from, to: bounds.to, maxResults: 1, deadline: bounds.deadline },
+                (id) => ({ type: 'next', id, revision: snapshot.revision, text: snapshot.text, query: { ...query }, offset, ...bounds }),
+                (reply) => {
+                    if (reply.type !== 'next') {
+                        throw new EditorSearchError('error', 'The worker returned an unexpected cursor response.');
+                    }
+                    const range = reply.range;
+                    if (
+                        range !== null &&
+                        (!Number.isInteger(range.from) ||
+                            !Number.isInteger(range.to) ||
+                            range.from < (bounds.from ?? 0) ||
+                            range.to < range.from ||
+                            range.to > (bounds.to ?? snapshot.text.length) ||
+                            splitsSurrogate(snapshot.text, range.from) ||
+                            splitsSurrogate(snapshot.text, range.to))
+                    ) {
+                        throw new EditorSearchError('error', 'The worker returned invalid cursor bounds.');
+                    }
+                    return range;
+                }
+            );
+        },
+        replacements(snapshot, query, replacement, options = {}) {
+            const { from, to, preserveCase } = options;
+            const maxEdits = options.maxEdits ?? 1000;
+            const maxCharacters = options.maxCharacters ?? MAX_REPLACEMENT_CHARACTERS;
+            return run(
+                snapshot,
+                query,
+                { from, to, maxResults: 1, deadline: options.deadline },
+                (id) => ({
+                    type: 'replacements',
+                    id,
+                    revision: snapshot.revision,
+                    text: snapshot.text,
+                    query: { ...query },
+                    from,
+                    to,
+                    preserveCase,
+                    replacement,
+                    maxEdits,
+                    maxCharacters
+                }),
+                (reply) => {
+                    if (reply.type !== 'replacements') {
+                        throw new EditorSearchError('error', 'The worker returned an unexpected replacement response.');
+                    }
+                    if (reply.ranges.length % 3 !== 0 || reply.ranges.length / 3 > maxEdits || reply.text.length > maxCharacters) {
+                        throw new EditorSearchError('error', 'The worker returned an invalid replacement page.');
+                    }
+                    let characters = 0;
+                    let previous = from ?? 0;
+                    let previousEmpty = false;
+                    for (let index = 0; index < reply.ranges.length; index += 3) {
+                        const start = reply.ranges[index]!,
+                            end = reply.ranges[index + 1]!;
+                        if (
+                            start < previous ||
+                            (previousEmpty && start === previous) ||
+                            end < start ||
+                            end > (to ?? snapshot.text.length) ||
+                            splitsSurrogate(snapshot.text, start) ||
+                            splitsSurrogate(snapshot.text, end)
+                        ) {
+                            throw new EditorSearchError('error', 'The worker returned invalid replacement bounds.');
+                        }
+                        previous = end;
+                        previousEmpty = start === end;
+                        characters += reply.ranges[index + 2]!;
+                    }
+                    if (characters !== reply.text.length) {
+                        throw new EditorSearchError('error', 'The worker returned inconsistent replacement lengths.');
+                    }
+                    if (reply.next !== null) {
+                        const index = reply.ranges.length - 3;
+                        if (index < 0) {
+                            throw new EditorSearchError('error', 'The worker returned an empty replacement continuation.');
+                        }
+                        const start = reply.ranges[index],
+                            end = reply.ranges[index + 1];
+                        const resume = end! + (start === end ? ((snapshot.text.codePointAt(end!) ?? 0) > 0xffff ? 2 : 1) : 0);
+                        if (reply.next !== resume || reply.next > (to ?? snapshot.text.length)) {
+                            throw new EditorSearchError('error', 'The worker returned an invalid replacement continuation.');
+                        }
+                    }
+                    return { revision: reply.revision, ranges: reply.ranges, text: reply.text, next: reply.next };
+                },
+                () => {
+                    if (
+                        !Number.isInteger(maxEdits) ||
+                        maxEdits < 1 ||
+                        maxEdits > MAX_REPLACEMENT_PAGE ||
+                        !Number.isInteger(maxCharacters) ||
+                        maxCharacters < 0 ||
+                        maxCharacters > MAX_REPLACEMENT_CHARACTERS
+                    ) {
+                        throw new EditorSearchError('range', 'Replacement pages need a positive edit limit and a bounded character limit.');
+                    }
+                }
+            );
+        },
+        cancel() {
+            transport.cancel();
+        },
+        release() {
+            transport.release();
+        },
+        dispose() {
+            transport.dispose();
+        }
+    };
+}

package/src/search-protocol.ts

@@ -0,0 +1,100 @@
+import type { FindMatch } from '@adecore/editor-core';
+import type { EditorFindQuery } from './types.ts';
+
+export const SEARCH_LIMIT = 10000;
+export const MAX_REPLACEMENT_PAGE = 10000;
+export const MAX_REPLACEMENT_CHARACTERS = 4_000_000;
+
+export interface EditorSearchSnapshot {
+    readonly revision: number;
+    readonly text: string;
+}
+
+export interface EditorSearchOptions {
+    /* Milliseconds including startup and snapshot posting; overrides the client deadline. */
+    readonly deadline?: number;
+    readonly from?: number;
+    readonly to?: number;
+    readonly maxResults?: number;
+}
+
+export interface EditorSearchResult {
+    readonly revision: number;
+    /* Pairs of UTF-16 offsets; search marks do not transfer matched text or captures. */
+    readonly ranges: Uint32Array;
+    readonly limited: boolean;
+}
+
+export interface EditorSearchRange {
+    readonly from: number;
+    readonly to: number;
+}
+
+export interface EditorSearchNextOptions {
+    readonly deadline?: number;
+    readonly from?: number;
+    readonly to?: number;
+    readonly backwards?: boolean;
+    readonly wrap?: boolean;
+}
+
+export interface EditorSearchReplacementOptions {
+    readonly deadline?: number;
+    readonly from?: number;
+    readonly to?: number;
+    readonly preserveCase?: boolean;
+    readonly maxEdits?: number;
+    readonly maxCharacters?: number;
+}
+
+export interface EditorSearchReplacements {
+    readonly revision: number;
+    /* Triples [from, to, replacement length], indexing the concatenated text. */
+    readonly ranges: Uint32Array;
+    readonly text: string;
+    readonly next: number | null;
+}
+
+export type EditorSearchMatch = Omit<FindMatch, 'revision' | 'text'>;
+
+interface SearchInput {
+    readonly id: number;
+    readonly revision: number;
+    readonly text?: string;
+    readonly query: EditorFindQuery;
+}
+
+export type EditorSearchInput =
+    | (SearchInput & { readonly type: 'search'; readonly from?: number; readonly to?: number; readonly maxResults: number })
+    | (SearchInput & { readonly type: 'match'; readonly from: number; readonly to: number })
+    | (SearchInput & {
+          readonly type: 'next';
+          readonly offset: number;
+          readonly from?: number;
+          readonly to?: number;
+          readonly backwards?: boolean;
+          readonly wrap?: boolean;
+      })
+    | (SearchInput & {
+          readonly type: 'replacements';
+          readonly from?: number;
+          readonly to?: number;
+          readonly replacement: string;
+          readonly preserveCase?: boolean;
+          readonly maxEdits: number;
+          readonly maxCharacters: number;
+      });
+
+export type EditorSearchOutput =
+    | { readonly type: 'ready' }
+    | ({ readonly type: 'matches'; readonly id: number } & EditorSearchResult)
+    | { readonly type: 'match'; readonly id: number; readonly revision: number; readonly match: EditorSearchMatch | null }
+    | { readonly type: 'next'; readonly id: number; readonly revision: number; readonly range: EditorSearchRange | null }
+    | ({ readonly type: 'replacements'; readonly id: number } & EditorSearchReplacements)
+    | {
+          readonly type: 'error';
+          readonly id: number;
+          readonly revision: number;
+          readonly kind: 'syntax' | 'range' | 'snapshot' | 'error';
+          readonly message: string;
+      };

package/src/search-worker.ts

@@ -0,0 +1,171 @@
+import { iterateMatches, findMatchFrom, replacementText, type FindMatch, type FindOptions } from '@adecore/editor-core';
+import {
+    SEARCH_LIMIT,
+    MAX_REPLACEMENT_PAGE,
+    MAX_REPLACEMENT_CHARACTERS,
+    type EditorSearchInput,
+    type EditorSearchOutput,
+    type EditorSearchSnapshot
+} from './search-protocol.ts';
+
+export { createSearchClient, EditorSearchError, type EditorSearchClient, type EditorSearchClientOptions, type EditorSearchErrorKind } from './search-client.ts';
+export type {
+    EditorSearchInput,
+    EditorSearchOptions,
+    EditorSearchOutput,
+    EditorSearchResult,
+    EditorSearchSnapshot,
+    EditorSearchMatch,
+    EditorSearchRange,
+    EditorSearchNextOptions,
+    EditorSearchReplacementOptions,
+    EditorSearchReplacements
+} from './search-protocol.ts';
+
+const MAX_CAPTURE_CHARACTERS = 4_000_000;
+
+export interface EditorSearchWorkerEndpoint {
+    addEventListener(type: 'message', listener: (event: MessageEvent<EditorSearchInput>) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent<EditorSearchInput>) => void): void;
+    postMessage(message: EditorSearchOutput, options?: { transfer: Transferable[] }): void;
+}
+
+function findOptions(request: EditorSearchInput): FindOptions {
+    return { caseSensitive: request.query.caseSensitive, wholeWord: request.query.wholeWord, regex: request.query.regex, from: request.from, to: request.to };
+}
+
+function captureMatch(found: FindMatch) {
+    let characters = 0;
+    for (const value of found.captures) {
+        characters += value?.length ?? 0;
+    }
+    for (const value of Object.values(found.groups ?? {})) {
+        characters += value?.length ?? 0;
+    }
+    if (characters > MAX_CAPTURE_CHARACTERS) {
+        throw new RangeError('Search captures exceed the response size limit.');
+    }
+    return { from: found.from, to: found.to, captures: found.captures, groups: found.groups, regex: found.regex };
+}
+
+function searchReply(request: EditorSearchInput, snapshot: EditorSearchSnapshot): Exclude<EditorSearchOutput, { type: 'ready' | 'error' }> {
+    const { text } = snapshot;
+    const options = findOptions(request);
+    const header = { id: request.id, revision: request.revision };
+    if (request.type === 'next') {
+        let found: FindMatch | null = null;
+        if (request.backwards) {
+            let last: FindMatch | null = null;
+            for (const match of iterateMatches(text, request.query.text, request.revision, options)) {
+                last = match;
+                if (match.from < request.offset) {
+                    found = match;
+                } else if (found !== null || request.wrap === false) {
+                    break;
+                }
+            }
+            found ??= request.wrap === false ? null : last;
+        } else {
+            found = findMatchFrom(text, request.query.text, request.revision, request.offset, { ...options, wrap: request.wrap });
+        }
+        return { type: 'next', ...header, range: found === null ? null : { from: found.from, to: found.to } };
+    }
+    if (request.type === 'match') {
+        const found = iterateMatches(text, request.query.text, request.revision, { ...options, maxResults: 1 }).next().value;
+        return { type: 'match', ...header, match: found && found.from === request.from && found.to === request.to ? captureMatch(found) : null };
+    }
+    if (request.type === 'replacements') {
+        if (
+            !Number.isInteger(request.maxEdits) ||
+            request.maxEdits < 1 ||
+            request.maxEdits > MAX_REPLACEMENT_PAGE ||
+            !Number.isInteger(request.maxCharacters) ||
+            request.maxCharacters < 0 ||
+            request.maxCharacters > MAX_REPLACEMENT_CHARACTERS
+        ) {
+            throw new RangeError('Replacement pages need a positive edit limit and a bounded character limit.');
+        }
+        const ranges: number[] = [],
+            pieces: string[] = [];
+        let characters = 0;
+        let resume = request.from ?? 0;
+        let next: number | null = null;
+        for (const match of iterateMatches(text, request.query.text, request.revision, { ...options, maxResults: request.maxEdits + 1 })) {
+            if (pieces.length === request.maxEdits) {
+                next = resume;
+                break;
+            }
+            const replacement = replacementText(text, match, request.replacement, false, request.preserveCase, request.maxCharacters);
+            if (characters + replacement.length > request.maxCharacters) {
+                if (pieces.length === 0) {
+                    throw new RangeError('One replacement exceeds the response size limit.');
+                }
+                next = resume;
+                break;
+            }
+            characters += replacement.length;
+            ranges.push(match.from, match.to, replacement.length);
+            pieces.push(replacement);
+            // Resuming after an empty match must skip the same full code point as the matcher.
+            resume = match.to + (match.from === match.to ? ((text.codePointAt(match.to) ?? 0) > 0xffff ? 2 : 1) : 0);
+        }
+        return { type: 'replacements', ...header, ranges: Uint32Array.from(ranges), text: pieces.join(''), next };
+    }
+    if (!Number.isInteger(request.maxResults) || request.maxResults < 0 || request.maxResults > SEARCH_LIMIT) {
+        throw new RangeError(`Search results must be limited to ${SEARCH_LIMIT} matches or fewer.`);
+    }
+    const offsets: number[] = [];
+    let limited = false;
+    for (const match of iterateMatches(text, request.query.text, request.revision, { ...options, maxResults: request.maxResults + 1 })) {
+        if (offsets.length === request.maxResults * 2) {
+            limited = true;
+            break;
+        }
+        offsets.push(match.from, match.to);
+    }
+    return { type: 'matches', ...header, ranges: Uint32Array.from(offsets), limited };
+}
+
+/* A running RegExp can only be interrupted by terminating its worker. */
+export function serveEditorSearch(endpoint: EditorSearchWorkerEndpoint): () => void {
+    let snapshot: EditorSearchSnapshot | undefined;
+    const listener = ({ data: request }: MessageEvent<EditorSearchInput>): void => {
+        try {
+            if (!Number.isSafeInteger(request.revision) || request.revision < 0) {
+                throw new RangeError('The search revision must be a nonnegative safe integer.');
+            }
+            if (request.text !== undefined) {
+                snapshot = { revision: request.revision, text: request.text };
+            }
+            if (snapshot === undefined || snapshot.revision !== request.revision) {
+                endpoint.postMessage({
+                    type: 'error',
+                    id: request.id,
+                    revision: request.revision,
+                    kind: 'snapshot',
+                    message: 'The search worker needs the text of this revision.'
+                });
+                return;
+            }
+            const response = searchReply(request, snapshot);
+            endpoint.postMessage(
+                response,
+                response.type === 'matches' || response.type === 'replacements' ? { transfer: [response.ranges.buffer] } : undefined
+            );
+        } catch (error) {
+            endpoint.postMessage({
+                type: 'error',
+                id: request.id,
+                revision: request.revision,
+                kind: error instanceof SyntaxError ? 'syntax' : error instanceof RangeError ? 'range' : 'error',
+                message: error instanceof Error ? error.message : String(error)
+            });
+        }
+    };
+    endpoint.addEventListener('message', listener);
+    endpoint.postMessage({ type: 'ready' });
+    return () => {
+        endpoint.removeEventListener('message', listener);
+        snapshot = undefined;
+    };
+}

package/src/semantic.ts

@@ -1,4 +1,4 @@
-import type { LineToken } from './types.ts';
+import type { LineToken, LineTokenKind } from './types.ts';
 
 /* A stretch of one line, in characters from its start, that a language server colors. */
 export interface SemanticSpan {
@@ -6,6 +6,8 @@ export interface SemanticSpan {
     readonly to: number;
     readonly color: string;
     readonly fontStyle: number;
+    /* The span applies only over base tokens of this kind. */
+    readonly within?: LineTokenKind;
 }
 
 /*
@@ -44,7 +46,11 @@ export function overlayTokens(base: readonly LineToken[], spans: readonly Semant
                 at = current.from;
             } else {
                 const stop = Math.min(end, current.to);
-                push(stop - at, current.color, current.fontStyle);
+                if (current.within === undefined || token.kind === current.within) {
+                    push(stop - at, current.color, current.fontStyle);
+                } else {
+                    push(stop - at, token.color, token.fontStyle);
+                }
                 at = stop;
             }
         }