@smartdoca/search-host 0.1.0

package/dist/LICENSING.md

@@ -0,0 +1,57 @@
+# Licensing
+
+[简体中文](LICENSING.zh-CN.md)
+
+Doca uses a dual-licensing model for code owned by the Doca copyright holders.
+
+## Open-source license
+
+Unless a file or package says otherwise, Doca-owned code in this repository is
+available under the GNU Affero General Public License version 3 only
+(`AGPL-3.0-only`). The full license text is in [LICENSE](LICENSE).
+
+The AGPL permits commercial use. When its conditions apply, it requires the
+corresponding source to remain available under the AGPL, including for modified
+versions offered to users over a network. “Open source” and “free of charge” are
+not the same thing, and the AGPL obligations do not depend on whether an operator
+charges money.
+
+## Commercial license
+
+Organizations that want to use Doca-owned code in a proprietary product without
+the AGPL obligations may obtain a separate commercial license from the Doca
+copyright holders. A commercial license exists only when both parties have
+entered into a written agreement. This repository does not itself grant that
+alternative license.
+
+## Packages and editors
+
+The same licensing direction applies to Doca-owned packages and editors,
+including the Doca plugin SDK and the Slate, presentation, spreadsheet,
+Markdown, and canvas editor packages. Each released npm artifact must:
+
+- carry an accurate license field and license notice;
+- link to the public source repository and the exact source tag for that version;
+- include the build scripts and dependency lock needed to produce the artifact;
+- preserve all notices and license obligations of third-party components.
+
+The historical archives under `vendor/` are development and recovery inputs.
+They are not the long-term public distribution channel. Before the public
+release, active editor dependencies must be rebuilt from their public tagged
+sources, published to npm, and consumed by Doca through registry versions.
+
+## Third-party software and assets
+
+The dual license covers only material for which the Doca copyright holders can
+grant these rights. Third-party libraries, fonts, media, generated artifacts,
+and other bundled material retain their own licenses. Their notices and source
+or attribution requirements must be followed independently.
+
+No trademark rights are granted by either the AGPL or this licensing summary.
+
+## Contributions
+
+Dual licensing requires the project to retain the rights needed to offer future
+commercial licenses. See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting
+code. This document is a project policy summary, not a substitute for the
+license text or legal advice.

package/dist/LICENSING.zh-CN.md

@@ -0,0 +1,48 @@
+# 许可说明
+
+[English](LICENSING.md)
+
+Doca 对其版权所有者拥有权利的代码采用双许可模式。
+
+## 开源许可证
+
+除非文件或包中另有说明，本仓库内由 Doca 版权所有者拥有的代码默认采用
+GNU Affero General Public License version 3 only（`AGPL-3.0-only`）。完整条款见
+[LICENSE](LICENSE)。
+
+AGPL 允许商业使用。当其条件适用时，分发软件或将修改后的版本作为网络服务提供给
+用户，需要继续按 AGPL 提供对应源码。是否收费并不是 AGPL 义务的判断条件，“开源”
+也不等于“免费”。
+
+## 商业许可证
+
+希望在闭源产品中使用 Doca 自研代码、且不希望承担 AGPL 义务的组织，可以向 Doca
+版权所有者申请单独的商业许可证。只有双方签署书面协议后，商业许可证才成立；本仓库
+本身不授予该替代许可证。
+
+## 子包与编辑器
+
+同一许可方向适用于 Doca 自研的子包和编辑器，包括插件 SDK，以及 Slate 富文本、
+演示文稿、表格、Markdown 和画板编辑器。每个正式发布的 npm 制品必须：
+
+- 使用准确的许可证字段并携带许可证说明；
+- 链接公开源码仓库以及与该版本精确对应的 Git tag；
+- 提供生成该制品所需的构建脚本和依赖锁文件；
+- 保留所有第三方组件要求的许可证及声明。
+
+`vendor/` 中的历史压缩包是开发和恢复输入，不作为长期公开分发渠道。正式开源前，
+当前使用的编辑器依赖应从公开且已打 tag 的源码重新构建并发布到 npm，Doca 再改为
+使用 registry 版本。
+
+## 第三方软件与素材
+
+双许可只覆盖 Doca 版权所有者有权授予许可的内容。第三方库、字体、媒体、生成产物及
+其他随附内容继续适用各自许可证，其声明、源码提供或署名要求需要独立履行。
+
+AGPL 和本文均不授予商标使用权。
+
+## 外部贡献
+
+双许可要求项目持续保有提供商业许可证所需的权利。提交代码前请阅读
+[CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。本文只是项目政策摘要，不能替代
+许可证原文或专业法律意见。

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./naming.js";
+export * from "./registry.js";
+export * from "./search-host.js";
+export * from "./memory-provider.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./naming.js";
+export * from "./registry.js";
+export * from "./search-host.js";
+export * from "./memory-provider.js";

package/dist/memory-provider.d.ts

@@ -0,0 +1,26 @@
+import type { SearchAliasSwap, SearchIndexMetadata, SearchProjection, SearchProvider, SearchProviderHit, SearchProviderQuery, SearchSourceDescriptor, SearchTombstone } from "./types.js";
+export interface InMemorySearchProviderOptions {
+    readonly now?: () => Date;
+}
+/**
+ * A deterministic provider intended for unit tests and local composition. It
+ * implements the same engine-neutral lifecycle used by production adapters.
+ */
+export declare class InMemorySearchProvider implements SearchProvider {
+    #private;
+    constructor(options?: InMemorySearchProviderOptions);
+    createIndex(name: string, descriptor: SearchSourceDescriptor): Promise<void>;
+    deleteIndex(name: string): Promise<void>;
+    inspectIndex(name: string): Promise<SearchIndexMetadata | undefined>;
+    resolveAlias(alias: string): Promise<string | undefined>;
+    swapAlias(alias: string, indexName: string): Promise<SearchAliasSwap>;
+    upsertProjections(indexName: string, projections: readonly SearchProjection[]): Promise<void>;
+    deleteProjections(indexName: string, documentIds: readonly string[]): Promise<void>;
+    queryIndex(indexName: string, request: SearchProviderQuery): Promise<readonly SearchProviderHit[]>;
+    putTombstones(tombstones: readonly SearchTombstone[]): Promise<void>;
+    deleteTombstones(sourceKey: string, documentIds: readonly string[]): Promise<void>;
+    listTombstones(sourceKey: string): Promise<readonly SearchTombstone[]>;
+    setQueryFailure(indexName: string, error?: unknown): void;
+    listIndexes(): readonly string[];
+    getProjection(indexName: string, documentId: string): SearchProjection | undefined;
+}

package/dist/memory-provider.js

@@ -0,0 +1,163 @@
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function copyDescriptor(descriptor) {
+    return {
+        pluginId: descriptor.pluginId,
+        sourceId: descriptor.sourceId,
+        schemaVersion: descriptor.schemaVersion,
+        renderer: { ...descriptor.renderer },
+    };
+}
+function copyProjection(projection) {
+    return {
+        id: projection.id,
+        text: projection.text,
+        metadata: projection.metadata ? { ...projection.metadata } : undefined,
+    };
+}
+function occurrences(haystack, needle) {
+    let count = 0;
+    let offset = 0;
+    while (offset <= haystack.length - needle.length) {
+        const match = haystack.indexOf(needle, offset);
+        if (match < 0)
+            break;
+        count++;
+        offset = match + needle.length;
+    }
+    return count;
+}
+/**
+ * A deterministic provider intended for unit tests and local composition. It
+ * implements the same engine-neutral lifecycle used by production adapters.
+ */
+export class InMemorySearchProvider {
+    #indices = new Map();
+    #aliases = new Map();
+    #tombstones = new Map();
+    #queryFailures = new Map();
+    #now;
+    constructor(options = {}) {
+        this.#now = options.now ?? (() => new Date());
+    }
+    async createIndex(name, descriptor) {
+        if (this.#indices.has(name))
+            throw new Error(`Search index already exists: ${name}`);
+        this.#indices.set(name, {
+            metadata: {
+                name,
+                descriptor: copyDescriptor(descriptor),
+                createdAt: this.#now().toISOString(),
+            },
+            documents: new Map(),
+        });
+    }
+    async deleteIndex(name) {
+        this.#indices.delete(name);
+        for (const [alias, target] of this.#aliases)
+            if (target === name)
+                this.#aliases.delete(alias);
+        this.#queryFailures.delete(name);
+    }
+    async inspectIndex(name) {
+        const metadata = this.#indices.get(name)?.metadata;
+        return metadata
+            ? { ...metadata, descriptor: copyDescriptor(metadata.descriptor) }
+            : undefined;
+    }
+    async resolveAlias(alias) {
+        return this.#aliases.get(alias);
+    }
+    async swapAlias(alias, indexName) {
+        if (!this.#indices.has(indexName))
+            throw new Error(`Search index does not exist: ${indexName}`);
+        const previous = this.#aliases.get(alias);
+        this.#aliases.set(alias, indexName);
+        return {
+            activeIndex: indexName,
+            ...(previous ? { previousIndex: previous } : {}),
+        };
+    }
+    async upsertProjections(indexName, projections) {
+        const index = this.#requireIndex(indexName);
+        for (const projection of projections)
+            index.documents.set(projection.id, copyProjection(projection));
+    }
+    async deleteProjections(indexName, documentIds) {
+        const index = this.#requireIndex(indexName);
+        for (const id of documentIds)
+            index.documents.delete(id);
+    }
+    async queryIndex(indexName, request) {
+        const resolved = this.#aliases.get(indexName) ?? indexName;
+        if (this.#queryFailures.has(resolved))
+            throw this.#queryFailures.get(resolved);
+        const index = this.#requireIndex(resolved);
+        const query = request.query.normalize("NFKC").toLowerCase();
+        const terms = query.trim() ? query.trim().split(/\s+/u) : [];
+        const candidates = request.candidateIds
+            ? new Set(request.candidateIds)
+            : undefined;
+        const hits = [];
+        for (const projection of index.documents.values()) {
+            if (candidates && !candidates.has(projection.id))
+                continue;
+            const text = projection.text.normalize("NFKC").toLowerCase();
+            const score = terms.length === 0
+                ? 1
+                : terms.reduce((total, term) => total + occurrences(text, term), 0);
+            if (score > 0)
+                hits.push({ id: projection.id, score });
+        }
+        const ranked = hits.sort((left, right) => right.score - left.score || compareText(left.id, right.id));
+        return request.limit === undefined
+            ? ranked
+            : ranked.slice(0, request.limit);
+    }
+    async putTombstones(tombstones) {
+        for (const tombstone of tombstones) {
+            let source = this.#tombstones.get(tombstone.sourceKey);
+            if (!source) {
+                source = new Map();
+                this.#tombstones.set(tombstone.sourceKey, source);
+            }
+            source.set(tombstone.documentId, { ...tombstone });
+        }
+    }
+    async deleteTombstones(sourceKey, documentIds) {
+        const source = this.#tombstones.get(sourceKey);
+        if (!source)
+            return;
+        for (const id of documentIds)
+            source.delete(id);
+        if (source.size === 0)
+            this.#tombstones.delete(sourceKey);
+    }
+    async listTombstones(sourceKey) {
+        return [...(this.#tombstones.get(sourceKey)?.values() ?? [])]
+            .sort((left, right) => compareText(left.documentId, right.documentId))
+            .map((tombstone) => ({ ...tombstone }));
+    }
+    setQueryFailure(indexName, error) {
+        const resolved = this.#aliases.get(indexName) ?? indexName;
+        if (error === undefined)
+            this.#queryFailures.delete(resolved);
+        else
+            this.#queryFailures.set(resolved, error);
+    }
+    listIndexes() {
+        return [...this.#indices.keys()].sort(compareText);
+    }
+    getProjection(indexName, documentId) {
+        const resolved = this.#aliases.get(indexName) ?? indexName;
+        const projection = this.#indices.get(resolved)?.documents.get(documentId);
+        return projection ? copyProjection(projection) : undefined;
+    }
+    #requireIndex(name) {
+        const index = this.#indices.get(name);
+        if (!index)
+            throw new Error(`Search index does not exist: ${name}`);
+        return index;
+    }
+}

package/dist/naming.d.ts

@@ -0,0 +1,14 @@
+import type { SearchSourceDescriptor } from "./types.js";
+export declare function validateSearchSourceDescriptor(descriptor: SearchSourceDescriptor): void;
+export declare function encodeIndexComponent(value: string): string;
+export declare function searchSourceKey(descriptor: Pick<SearchSourceDescriptor, "pluginId" | "sourceId">): string;
+export interface SearchIndexNames {
+    readonly alias: string;
+    readonly version: (version: string) => string;
+}
+/**
+ * Alias names are stable across schema changes; physical names carry both the
+ * schema and rebuild version so an alias swap can publish atomically.
+ */
+export declare function searchIndexNames(descriptor: SearchSourceDescriptor, namespace?: string): SearchIndexNames;
+export declare function sameSearchSource(left: SearchSourceDescriptor, right: SearchSourceDescriptor): boolean;

package/dist/naming.js

@@ -0,0 +1,46 @@
+const encoder = new TextEncoder();
+function requireText(value, field) {
+    if (value.trim().length === 0)
+        throw new TypeError(`${field} must be a non-empty string`);
+}
+export function validateSearchSourceDescriptor(descriptor) {
+    requireText(descriptor.pluginId, "pluginId");
+    requireText(descriptor.sourceId, "sourceId");
+    requireText(descriptor.renderer.kind, "renderer.kind");
+    if (!Number.isSafeInteger(descriptor.schemaVersion) ||
+        descriptor.schemaVersion < 1)
+        throw new TypeError("schemaVersion must be a positive safe integer");
+    if (descriptor.renderer.version !== undefined &&
+        (!Number.isSafeInteger(descriptor.renderer.version) ||
+            descriptor.renderer.version < 1))
+        throw new TypeError("renderer.version must be a positive safe integer");
+}
+export function encodeIndexComponent(value) {
+    requireText(value, "index component");
+    const bytes = encoder.encode(value);
+    return `${bytes.length}_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+export function searchSourceKey(descriptor) {
+    return `${encodeIndexComponent(descriptor.pluginId)}/${encodeIndexComponent(descriptor.sourceId)}`;
+}
+/**
+ * Alias names are stable across schema changes; physical names carry both the
+ * schema and rebuild version so an alias swap can publish atomically.
+ */
+export function searchIndexNames(descriptor, namespace = "doca_search") {
+    validateSearchSourceDescriptor(descriptor);
+    const prefix = [
+        encodeIndexComponent(namespace),
+        encodeIndexComponent(descriptor.pluginId),
+        encodeIndexComponent(descriptor.sourceId),
+    ].join("__");
+    return {
+        alias: `${prefix}__current`,
+        version: (version) => `${prefix}__schema_${descriptor.schemaVersion}__version_${encodeIndexComponent(version)}`,
+    };
+}
+export function sameSearchSource(left, right) {
+    return (left.pluginId === right.pluginId &&
+        left.sourceId === right.sourceId &&
+        left.schemaVersion === right.schemaVersion);
+}

package/dist/registry.d.ts

@@ -0,0 +1,27 @@
+import type { MaybePromise, SearchSource, SearchSourceEffect } from "./types.js";
+export declare class DuplicateSearchSourceError extends Error {
+    readonly sourceKey: string;
+    constructor(sourceKey: string);
+}
+export declare class DisposedSearchSourceRegistryError extends Error {
+    constructor();
+}
+export interface SearchSourceLease<TContext = unknown, TValue = unknown> {
+    readonly key: string;
+    readonly source: SearchSource<TContext, TValue>;
+    dispose(): Promise<void>;
+}
+/**
+ * The registry owns each installed effect until its lease or the registry is
+ * disposed. Duplicate effect acquisitions are rolled back immediately.
+ */
+export declare class SearchSourceRegistry<TContext = unknown> {
+    #private;
+    register<TValue>(source: SearchSource<TContext, TValue>, cleanup?: () => MaybePromise<void>): SearchSourceLease<TContext, TValue>;
+    install<TValue>(effect: SearchSourceEffect<TContext, TValue>): Promise<SearchSourceLease<TContext, TValue>>;
+    get(source: string | Pick<SearchSource<TContext>["descriptor"], "pluginId" | "sourceId">): SearchSource<TContext, any> | undefined;
+    list(): readonly SearchSource<TContext, any>[];
+    get size(): number;
+    get disposed(): boolean;
+    dispose(): Promise<void>;
+}

package/dist/registry.js

@@ -0,0 +1,95 @@
+import { searchSourceKey, validateSearchSourceDescriptor } from "./naming.js";
+export class DuplicateSearchSourceError extends Error {
+    sourceKey;
+    constructor(sourceKey) {
+        super(`Search source is already registered: ${sourceKey}`);
+        this.name = "DuplicateSearchSourceError";
+        this.sourceKey = sourceKey;
+    }
+}
+export class DisposedSearchSourceRegistryError extends Error {
+    constructor() {
+        super("Search source registry has been disposed");
+        this.name = "DisposedSearchSourceRegistryError";
+    }
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * The registry owns each installed effect until its lease or the registry is
+ * disposed. Duplicate effect acquisitions are rolled back immediately.
+ */
+export class SearchSourceRegistry {
+    #entries = new Map();
+    #disposed = false;
+    register(source, cleanup) {
+        if (this.#disposed)
+            throw new DisposedSearchSourceRegistryError();
+        validateSearchSourceDescriptor(source.descriptor);
+        if (typeof source.authorize !== "function" ||
+            typeof source.hydrate !== "function")
+            throw new TypeError("Search sources must provide authorize and hydrate");
+        const key = searchSourceKey(source.descriptor);
+        if (this.#entries.has(key))
+            throw new DuplicateSearchSourceError(key);
+        const token = Symbol(key);
+        let active = true;
+        const release = async () => {
+            if (!active)
+                return;
+            active = false;
+            const current = this.#entries.get(key);
+            if (current?.token === token)
+                this.#entries.delete(key);
+            await cleanup?.();
+        };
+        this.#entries.set(key, { token, source, release });
+        return { key, source, dispose: release };
+    }
+    async install(effect) {
+        const resource = await effect.acquire();
+        try {
+            return this.register(resource.source, resource.dispose);
+        }
+        catch (error) {
+            if (!resource.dispose)
+                throw error;
+            try {
+                await resource.dispose();
+            }
+            catch (disposeError) {
+                throw new AggregateError([error, disposeError], "Search source installation and rollback both failed");
+            }
+            throw error;
+        }
+    }
+    get(source) {
+        const key = typeof source === "string" ? source : searchSourceKey(source);
+        return this.#entries.get(key)?.source;
+    }
+    list() {
+        return [...this.#entries.entries()]
+            .sort(([left], [right]) => compareText(left, right))
+            .map(([, entry]) => entry.source);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        const entries = [...this.#entries.values()];
+        this.#entries.clear();
+        const results = await Promise.allSettled(entries.map((entry) => entry.release()));
+        const failures = results
+            .filter((result) => result.status === "rejected")
+            .map((result) => result.reason);
+        if (failures.length)
+            throw new AggregateError(failures, "Failed to dispose search sources");
+    }
+}

package/dist/search-host.d.ts

@@ -0,0 +1,64 @@
+import { type SearchIndexNames } from "./naming.js";
+import { SearchSourceRegistry } from "./registry.js";
+import type { FederatedSearchResult, SearchProjection, SearchProvider, SearchSourceDescriptor } from "./types.js";
+export type SearchSourceReference = string | Pick<SearchSourceDescriptor, "pluginId" | "sourceId">;
+export interface ProjectionUpsertRequest {
+    readonly source: SearchSourceReference;
+    readonly projections: readonly SearchProjection[];
+}
+export interface ProjectionDeleteRequest {
+    readonly source: SearchSourceReference;
+    readonly documentIds: readonly string[];
+    readonly deletedAt?: Date;
+}
+export interface SearchRebuildRequest<TContext> {
+    readonly source: SearchSourceReference;
+    readonly context: TContext;
+    readonly version?: string;
+    readonly retainPrevious?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface SearchRebuildResult {
+    readonly alias: string;
+    readonly indexName: string;
+    readonly previousIndex?: string;
+    readonly projectionCount: number;
+}
+export interface SearchIndexSwitchRequest {
+    readonly source: SearchSourceReference;
+    readonly indexName: string;
+    readonly deletePrevious?: boolean;
+}
+export interface SearchIndexSwitchResult {
+    readonly alias: string;
+    readonly indexName: string;
+    readonly previousIndex?: string;
+}
+export interface FederatedSearchRequest<TContext> {
+    readonly query: string;
+    readonly context: TContext;
+    readonly sources?: readonly SearchSourceReference[];
+    readonly offset?: number;
+    readonly limit?: number;
+}
+export interface SearchHostOptions<TContext> {
+    readonly registry?: SearchSourceRegistry<TContext>;
+    readonly namespace?: string;
+    readonly now?: () => Date;
+    readonly rebuildBatchSize?: number;
+}
+export interface SearchHost<TContext = unknown> {
+    readonly registry: SearchSourceRegistry<TContext>;
+    indexNames(source: SearchSourceReference): SearchIndexNames;
+    upsertProjections(request: ProjectionUpsertRequest): Promise<void>;
+    deleteProjections(request: ProjectionDeleteRequest): Promise<void>;
+    rebuild(request: SearchRebuildRequest<TContext>): Promise<SearchRebuildResult>;
+    switchIndex(request: SearchIndexSwitchRequest): Promise<SearchIndexSwitchResult>;
+    query<TValue = unknown>(request: FederatedSearchRequest<TContext>): Promise<FederatedSearchResult<TValue>>;
+    dispose(): Promise<void>;
+}
+export declare class SearchSourceNotFoundError extends Error {
+    readonly source: SearchSourceReference;
+    constructor(source: SearchSourceReference);
+}
+export declare function createSearchHost<TContext = unknown>(provider: SearchProvider, options?: SearchHostOptions<TContext>): SearchHost<TContext>;