dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/lib/contract-wire.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 跨插件 HTTP 线协议（wire）。
+ *
+ * ## 为什么单独一层
+ *
+ * 契约库里原本放的是「每个插件各自都要用的通用件」——版本模型、磁盘布局、结果信封。
+ * HTTP 消费方需要与 table 的目录项、范围响应和单元格样式三个形状保持一致。
+ *
+ * 手抄的代价不是丑，是**漂移时不报错**：
+ *
+ * - 消费方写的是防御式解析（`typeof style.ff === 'string'`）。生产者把 `ff` 改名，
+ *   消费方不会崩，只是**静默不再画字体**。
+ * - 目录响应同理：字段改名后 `Array.isArray(body.workbooks)` 仍然为真，只是每一项
+ *   都过不了字段检查，于是**静默显示空列表**。
+ *
+ * 所以这里把形状定义一次，并且**同时提供类型与校验器**：生产者用它标注返回值（改名 →
+ * 编译不过），消费方用它做校验（改名 → 运行时明确报错，而不是降级）。
+ *
+ * ## 目前的范围
+ *
+ * Table 提供两条只读工作簿查询路由，供集成调用方读取：
+ *
+ * ```
+ * GET /data-sheet/workbooks.json
+ * GET /data-sheet/workbook/{workbookId}/range?sheet=&session=&range=&styles=
+ * ```
+ *
+ * 两条都由 table 生产。
+ *
+ * ## 不在这一层的东西
+ *
+ * 统一信封（`./envelope` 的 `Envelope<T,E>`）**没有**覆盖这两条路由，因为它的载荷放在
+ * `data` 下，而 table 的响应把载荷放在顶层。把 table 迁到信封等于重写它每一条响应的形状
+ * 和它自己的浏览器客户端（`workbookApi.ts`、独立工作簿页），是独立工程。
+ * `spec/contracts/envelope.json` 里的「尚未遵守」指的正是这件事，这里不假装它已解决。
+ */
+/** 单元格格式。字段名是 Univer 的短码，与 table 的存储格式一致。 */
+export interface SheetCellStyle {
+    /** 字体族 */
+    ff?: string;
+    /** 字号（磅） */
+    fs?: number;
+    /** 加粗 */
+    bl?: boolean;
+    /** 斜体 */
+    it?: boolean;
+    /** 下划线 */
+    ul?: boolean;
+    /** 删除线 */
+    st?: boolean;
+    /** 背景色，`#rrggbb` */
+    bg?: string;
+    /** 前景色，`#rrggbb` */
+    cl?: string;
+    /** 水平对齐 */
+    ht?: number;
+    /** 垂直对齐 */
+    vt?: number;
+    /** 文字旋转 */
+    tr?: number;
+    /** 数字格式 */
+    n?: string;
+}
+/** 一个 0-based、两端 inclusive 的矩形范围。 */
+export interface SheetRangeBounds {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+/** `GET /data-sheet/workbook/{id}/range` 的 200 响应体。 */
+export interface SheetRangeResponse {
+    ok: true;
+    workbookId: string;
+    workbookName: string;
+    /** 读取时的主干修订号；消费方可用来判断是否落后。 */
+    revision: number;
+    sheetId: string;
+    sheetName: string;
+    /** 实际返回的范围。请求未指定时是这张表的已用范围。 */
+    range: SheetRangeBounds;
+    /** 表头行；空表返回空数组而不是一个无名列。 */
+    columns: string[];
+    /** 数据行（不含表头）。 */
+    rows: unknown[][];
+    /**
+     * 覆盖**整个** `range`（含表头行）的格式矩阵，下标与 `rows` 对齐（`rows[0]` 对应
+     * `range.startRow + 1`）。只有请求带 `styles=1` 时才出现。
+     */
+    styles?: Array<Array<SheetCellStyle | null>>;
+    /** 请求的范围窄于已用范围时为 `true`，消费方据此继续取剩余部分。 */
+    truncated: boolean;
+}
+/** 目录里一张表的结构摘要。生产者可能带更多字段，消费方只应依赖这些。 */
+export interface WorkbookSheetSchema {
+    /** 列定义；对消费方是不透明的，只保证是数组。 */
+    columns?: unknown[];
+    /** 数据行数，不含表头行。 */
+    rowCount?: number;
+}
+/** 目录里的一张表。 */
+export interface WorkbookCatalogSheet {
+    id: string;
+    name: string;
+    schema?: WorkbookSheetSchema;
+}
+/** 目录里的一个工作簿。 */
+export interface WorkbookCatalogEntry {
+    id: string;
+    name: string;
+    /** 主干修订号；消费方可用作乐观并发基线。 */
+    revision: number;
+    /**
+     * 表数量，等于 `sheets.length`。生产者顺手给的冗余字段，消费方不必依赖它。
+     * 保留在契约里是因为它**确实在线上**，不写就等于契约漏了一半。
+     */
+    sheetCount: number;
+    /** 最后一次写入时间（ISO 8601）。 */
+    updatedAt: string;
+    sheets: WorkbookCatalogSheet[];
+}
+/** `GET /data-sheet/workbooks.json` 的 200 响应体。 */
+export interface WorkbookCatalogResponse {
+    ok: true;
+    workbooks: WorkbookCatalogEntry[];
+}
+/**
+ * table 的错误响应体。
+ *
+ * `code` 只在生产者能给出稳定错误码时出现（例如 `REVISION_CONFLICT`、
+ * `VALIDATION_ERROR`）；`error` 是给人看的一句话，消费方**不要**用它做判断。
+ * 冲突响应还会额外带 `expectedRevision` / `revision` / `conflict`。
+ */
+export interface WireErrorBody {
+    ok: false;
+    code?: string;
+    error: string;
+    expectedRevision?: number;
+    revision?: number;
+    conflict?: unknown;
+}
+/** `{ ok: false, error: string }`，忽略额外字段。 */
+export declare function isWireErrorBody(value: unknown): value is WireErrorBody;
+/** 严格校验一个目录响应：任何一项不合格就整体拒绝，而不是悄悄过滤掉。 */
+export declare function isWorkbookCatalogResponse(value: unknown): value is WorkbookCatalogResponse;
+/** 严格校验一个范围响应。 */
+export declare function isSheetRangeResponse(value: unknown): value is SheetRangeResponse;

package/lib/contract-wire.js

@@ -0,0 +1,99 @@
+/**
+ * 跨插件 HTTP 线协议（wire）。
+ *
+ * ## 为什么单独一层
+ *
+ * 契约库里原本放的是「每个插件各自都要用的通用件」——版本模型、磁盘布局、结果信封。
+ * HTTP 消费方需要与 table 的目录项、范围响应和单元格样式三个形状保持一致。
+ *
+ * 手抄的代价不是丑，是**漂移时不报错**：
+ *
+ * - 消费方写的是防御式解析（`typeof style.ff === 'string'`）。生产者把 `ff` 改名，
+ *   消费方不会崩，只是**静默不再画字体**。
+ * - 目录响应同理：字段改名后 `Array.isArray(body.workbooks)` 仍然为真，只是每一项
+ *   都过不了字段检查，于是**静默显示空列表**。
+ *
+ * 所以这里把形状定义一次，并且**同时提供类型与校验器**：生产者用它标注返回值（改名 →
+ * 编译不过），消费方用它做校验（改名 → 运行时明确报错，而不是降级）。
+ *
+ * ## 目前的范围
+ *
+ * Table 提供两条只读工作簿查询路由，供集成调用方读取：
+ *
+ * ```
+ * GET /data-sheet/workbooks.json
+ * GET /data-sheet/workbook/{workbookId}/range?sheet=&session=&range=&styles=
+ * ```
+ *
+ * 两条都由 table 生产。
+ *
+ * ## 不在这一层的东西
+ *
+ * 统一信封（`./envelope` 的 `Envelope<T,E>`）**没有**覆盖这两条路由，因为它的载荷放在
+ * `data` 下，而 table 的响应把载荷放在顶层。把 table 迁到信封等于重写它每一条响应的形状
+ * 和它自己的浏览器客户端（`workbookApi.ts`、独立工作簿页），是独立工程。
+ * `spec/contracts/envelope.json` 里的「尚未遵守」指的正是这件事，这里不假装它已解决。
+ */
+/** 是否为「不是对象」以外的任意值——所有校验器的第一道门。 */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `{ ok: false, error: string }`，忽略额外字段。 */
+export function isWireErrorBody(value) {
+    return isObject(value) && value.ok === false && typeof value.error === 'string';
+}
+/** 严格校验一个目录响应：任何一项不合格就整体拒绝，而不是悄悄过滤掉。 */
+export function isWorkbookCatalogResponse(value) {
+    if (!isObject(value) || value.ok !== true || !Array.isArray(value.workbooks))
+        return false;
+    return value.workbooks.every(entry => {
+        if (!isObject(entry))
+            return false;
+        if (typeof entry.id !== 'string' || typeof entry.name !== 'string')
+            return false;
+        if (typeof entry.revision !== 'number' || typeof entry.sheetCount !== 'number')
+            return false;
+        if (typeof entry.updatedAt !== 'string' || !Array.isArray(entry.sheets))
+            return false;
+        return entry.sheets.every(sheet => {
+            if (!isObject(sheet))
+                return false;
+            if (typeof sheet.id !== 'string' || typeof sheet.name !== 'string')
+                return false;
+            if (sheet.schema === undefined)
+                return true;
+            const schema = sheet.schema;
+            if (!isObject(schema))
+                return false;
+            if (schema.columns !== undefined && !Array.isArray(schema.columns))
+                return false;
+            return schema.rowCount === undefined || typeof schema.rowCount === 'number';
+        });
+    });
+}
+/** 严格校验一个范围响应。 */
+export function isSheetRangeResponse(value) {
+    if (!isObject(value) || value.ok !== true)
+        return false;
+    if (typeof value.workbookId !== 'string' || typeof value.sheetName !== 'string')
+        return false;
+    if (!Array.isArray(value.columns) || !value.columns.every(column => typeof column === 'string'))
+        return false;
+    if (!Array.isArray(value.rows))
+        return false;
+    if (typeof value.truncated !== 'boolean')
+        return false;
+    if (value.styles !== undefined) {
+        if (!Array.isArray(value.styles))
+            return false;
+        if (!value.styles.every(row => Array.isArray(row)))
+            return false;
+    }
+    if (value.range === undefined)
+        return false;
+    const range = value.range;
+    if (!isObject(range))
+        return false;
+    // 先取出局部常量再进闭包：TS 不会把 `value.range` 的收窄带进回调。
+    return ['startRow', 'startColumn', 'endRow', 'endColumn'].every(key => typeof range[key] === 'number');
+}

package/lib/contracts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared wire contracts and pure protocol helpers.
+ *
+ * This source lives in the existing private UI workspace package so DSH plugins
+ * can type-check against one canonical module. Client and host builds bundle the
+ * imported code into their plugin output; it is not a published runtime package.
+ */
+export * from './contract-envelope.js';
+export * from './contract-refs.js';
+export * from './contract-version.js';
+export * from './contract-layout.js';
+export * from './contract-wire.js';

package/lib/contracts.js

@@ -0,0 +1,12 @@
+/**
+ * Shared wire contracts and pure protocol helpers.
+ *
+ * This source lives in the existing private UI workspace package so DSH plugins
+ * can type-check against one canonical module. Client and host builds bundle the
+ * imported code into their plugin output; it is not a published runtime package.
+ */
+export * from './contract-envelope.js';
+export * from './contract-refs.js';
+export * from './contract-version.js';
+export * from './contract-layout.js';
+export * from './contract-wire.js';