@univerjs-pro/bases 0.25.0-insiders.20260608-e4336f7

package/lib/types/facade/f-base.d.ts

@@ -0,0 +1,362 @@
+import type { BaseDataModel, FieldId, IBaseSnapshot, ICommandService, IDisposable } from '@univerjs/core';
+import type { IBaseTableSearchResult } from '../search/base-search';
+import type { IBasePermissionService } from '../services/base-permission.service';
+import type { IBaseProjectionService } from '../services/base-projection.service';
+import type { IBaseEventMap } from './f-event';
+import { BaseEventName } from './f-event';
+import { FBasePermission } from './f-permission';
+import { FTable } from './f-table';
+export interface ICreateTableInput {
+    /** Optional table id. A random id is generated when omitted. */
+    id?: string;
+    /** Table display name. */
+    name: string;
+    /** Primary text field display name. */
+    primaryFieldName?: string;
+    /** Optional insertion index in the Base table order. */
+    index?: number;
+}
+export interface ISearchTableInput {
+    /** Search text. Blank queries return no matches. */
+    query: string;
+    /** Optional view id. When provided, records are searched in the view projection. */
+    viewId?: string;
+    /** Optional field ids to search. Defaults to visible/searchable fields. */
+    fieldIds?: ReadonlyArray<FieldId>;
+    /** Optional maximum number of matches. */
+    limit?: number;
+}
+export interface ICopyTableInput {
+    /** Optional table id for the copied table. A random id is generated when omitted. */
+    id?: string;
+    /** Optional copied table name. Defaults to `<source name> Copy`. */
+    name?: string;
+    /** Optional insertion index in the Base table order. */
+    index?: number;
+}
+export interface IBaseSchemaSnapshot {
+    id: string;
+    name: string;
+    tables: Array<{
+        id: string;
+        name: string;
+        primaryFieldId: string;
+        fieldIds: string[];
+        viewIds: string[];
+        recordCount: number;
+    }>;
+}
+/**
+ * Facade API object bound to a Base unit.
+ *
+ * A Base contains multiple tables. In spreadsheet terms this is similar to a workbook,
+ * while a Base table is similar to a worksheet.
+ *
+ * Use `FBase` for runtime edits and use `getSnapshot()` / `save()` only at the
+ * persistence boundary. Facade writes execute commands, so Base events,
+ * permissions, undo/redo, formula dirty ranges, and collaboration adapters see
+ * the same operations as UI edits.
+ *
+ * @example Load a server snapshot, edit it, and save it back
+ * ```ts
+ * const base = univerAPI.createBase(serverSnapshot);
+ * const table = await base.createTable({
+ *   id: 'tasks',
+ *   name: 'Tasks',
+ *   primaryFieldName: 'Title',
+ * });
+ * const status = await table.addField({
+ *   id: 'status',
+ *   name: 'Status',
+ *   type: 'singleSelect',
+ *   config: { options: [{ id: 'todo', name: 'Todo', color: 'blue' }] },
+ * });
+ * await table.addRecord({
+ *   id: 'task-1',
+ *   values: { [table.getPrimaryFieldId()]: 'Review protocol', [status.getId()]: 'todo' },
+ * });
+ * await saveBaseSnapshotToServer(base.save());
+ * ```
+ */
+export declare class FBase {
+    private readonly _base;
+    private readonly _commandService;
+    private readonly _projectionService;
+    private readonly _permissionService;
+    constructor(_base: BaseDataModel, _commandService: ICommandService, _projectionService: IBaseProjectionService, _permissionService: IBasePermissionService);
+    /**
+     * Get the underlying Base data model.
+     * @returns The Base data model.
+     * @example
+     * ```ts
+     * const model = base.getBase();
+     * ```
+     */
+    getBase(): BaseDataModel;
+    /**
+     * Get the Base unit id.
+     * @returns The Base id.
+     * @example
+     * ```ts
+     * console.log(base.getId());
+     * ```
+     */
+    getId(): string;
+    /**
+     * Get the Base name.
+     * @returns The Base name.
+     * @example
+     * ```ts
+     * console.log(base.getName());
+     * ```
+     */
+    getName(): string;
+    /**
+     * Get all non-deleted tables in this Base.
+     * @returns Table facade objects ordered by the Base table order.
+     * @example
+     * ```ts
+     * const tables = base.getTables();
+     * ```
+     */
+    getTables(): FTable[];
+    /**
+     * Get the current Base snapshot.
+     *
+     * The returned object is the persisted model shape. Use it for protocol
+     * payloads, storage, and snapshot comparison. Use facade mutation methods
+     * instead of mutating this object directly.
+     *
+     * @returns The current Base snapshot.
+     * @example
+     * ```ts
+     * const snapshot = base.getSnapshot();
+     * await request('/api/base/save', { method: 'POST', body: JSON.stringify(snapshot) });
+     * ```
+     */
+    getSnapshot(): IBaseSnapshot;
+    /**
+     * Save and return the current Base snapshot.
+     *
+     * This method intentionally returns a snapshot instead of performing I/O.
+     * The caller decides how to persist the payload, for example by sending it
+     * to the server-side protocol adapter.
+     *
+     * @returns The current Base snapshot.
+     * @example
+     * ```ts
+     * const snapshot = base.save();
+     * await server.saveBase(snapshot.id, snapshot);
+     * ```
+     */
+    save(): IBaseSnapshot;
+    /**
+     * Set the Base name.
+     * @param name The new Base name.
+     * @example
+     * ```ts
+     * await base.setName('Product Roadmap');
+     * ```
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * Get a table by id.
+     * @param tableId The table id.
+     * @returns The table facade, or null if the table does not exist.
+     * @example
+     * ```ts
+     * const table = base.getTable('table-1');
+     * ```
+     */
+    getTable(tableId: string): FTable | null;
+    /**
+     * Get a table by id.
+     * @param tableId The table id.
+     * @returns The table facade, or null if the table does not exist.
+     * @example
+     * ```ts
+     * const table = base.getTableById('table-1');
+     * ```
+     */
+    getTableById(tableId: string): FTable | null;
+    /**
+     * Get the first table matching a table name.
+     * @param name The table name.
+     * @returns The table facade, or null if no table matches.
+     * @example
+     * ```ts
+     * const table = base.getTableByName('Tasks');
+     * ```
+     */
+    getTableByName(name: string): FTable | null;
+    /**
+     * Create a table in this Base.
+     *
+     * The created table includes a primary text field. Provide `id` when the
+     * server or fixture needs deterministic ids; otherwise a random table id is
+     * generated.
+     *
+     * @param input Table creation options.
+     * `input.name` is required. `input.primaryFieldName` names the generated
+     * primary field. `input.index` inserts the table at a zero-based position in
+     * the Base table order.
+     * @returns The created table facade.
+     * @example
+     * ```ts
+     * const table = await base.createTable({
+     *   id: 'tasks',
+     *   name: 'Tasks',
+     *   primaryFieldName: 'Title',
+     * });
+     * ```
+     * @example Full table creation flow
+     * ```ts
+     * const table = await base.createTable({ id: 'tasks', name: 'Tasks', primaryFieldName: 'Title' });
+     * const status = await table.addField({ id: 'status', name: 'Status', type: 'text', config: {} });
+     * await table.addRecord({
+     *   id: 'task-1',
+     *   values: { [table.getPrimaryFieldId()]: 'Ship beta', [status.getId()]: 'todo' },
+     * });
+     * console.log(base.save().tables.tasks.records['task-1']);
+     * ```
+     */
+    createTable(input: ICreateTableInput): Promise<FTable>;
+    /**
+     * Insert a table in this Base.
+     * @param input Table creation options. Use `index` to control the table order.
+     * @returns The inserted table facade.
+     * @example
+     * ```ts
+     * const table = await base.insertTable({ name: 'Archive', index: 1 });
+     * ```
+     */
+    insertTable(input: ICreateTableInput): Promise<FTable>;
+    /**
+     * Rename a table.
+     * @param tableId The target table id.
+     * @param name The new table name.
+     * @example
+     * ```ts
+     * await base.renameTable('tasks', 'Roadmap');
+     * ```
+     */
+    renameTable(tableId: string, name: string): Promise<void>;
+    /**
+     * Delete a table.
+     * @param tableId The target table id.
+     * @example
+     * ```ts
+     * await base.deleteTable('archive');
+     * ```
+     */
+    deleteTable(tableId: string): Promise<void>;
+    /**
+     * Copy a table including fields, views, records, and resources.
+     *
+     * This is useful for templates and archive flows. The copied table keeps
+     * field ids, view ids, record ids, values, and resources from the source
+     * table unless future migration code rewrites them.
+     *
+     * @param tableId Source table id.
+     * @param input Optional copied table id, name, and insertion index. `id`
+     * defaults to a generated table id, `name` defaults to
+     * `"<source name> Copy"`, and `index` controls table order.
+     * @returns The copied table facade.
+     * @example
+     * ```ts
+     * const copied = await base.copyTable('tasks', { name: 'Tasks Archive' });
+     * ```
+     */
+    copyTable(tableId: string, input?: ICopyTableInput): Promise<FTable>;
+    /**
+     * Run multiple facade operations in a callback.
+     * @param fn A callback that receives this Base facade.
+     * @returns The callback result.
+     * @example
+     * ```ts
+     * await base.batch(async (tx) => {
+     *   await tx.createTable({ name: 'Tasks' });
+     * });
+     * ```
+     */
+    batch<T>(fn: (tx: FBase) => Promise<T>): Promise<T>;
+    /**
+     * Search records in a table.
+     *
+     * Search reads the current table snapshot. When `viewId` is provided, the
+     * search space follows that view projection, including hidden fields and
+     * projected row order.
+     *
+     * @param tableId The table id to search.
+     * @param input Search options. `query` is trimmed and blank queries return
+     * no matches. `viewId` searches in a view projection. `fieldIds` limits the
+     * searched fields. `limit` caps the number of matches.
+     * @returns Search result with the normalized query, total count, matched
+     * records, and matched field/cell information.
+     * @example
+     * ```ts
+     * const result = base.searchTable('tasks', {
+     *   query: 'release',
+     *   fieldIds: ['title', 'status'],
+     *   limit: 20,
+     * });
+     * ```
+     */
+    searchTable(tableId: string, input: ISearchTableInput): IBaseTableSearchResult;
+    /**
+     * Get a compact schema snapshot for agent/tooling use.
+     *
+     * `getSchema()` intentionally omits row values. Use it when an agent,
+     * server route, or prompt needs structure and ids without transferring the
+     * full data payload.
+     *
+     * @returns The Base schema without row values.
+     * @example
+     * ```ts
+     * console.log(base.getSchema().tables.map((table) => table.name));
+     * ```
+     */
+    getSchema(): IBaseSchemaSnapshot;
+    /**
+     * Get the permission facade for this Base.
+     *
+     * Permission changes affect Base command permission checks and can be
+     * hydrated from server-side authorization data.
+     *
+     * @returns The Base permission facade.
+     * @example
+     * ```ts
+     * base.getPermission().setTablePermission('tasks', { createRecord: false });
+     * ```
+     */
+    getPermission(): FBasePermission;
+    /**
+     * Add a Base event listener.
+     *
+     * Events are derived from executed Base commands. They are useful for
+     * server sync indicators, audit logs, demos, and agent tools that need to
+     * observe facade writes.
+     *
+     * @param event Base event name. Use `BaseEventName.TableChanged`,
+     * `FieldChanged`, `RecordChanged`, `CellValueChanged`, or `ViewChanged`.
+     * @param listener Event callback. The payload shape depends on the event
+     * name and includes ids, facade wrappers for live objects when available,
+     * and the original command payload.
+     * @returns A disposable listener handle.
+     * @example
+     * ```ts
+     * const disposable = base.addEvent(BaseEventName.RecordChanged, (event) => {
+     *   console.log(event.type, event.recordIds);
+     * });
+     * await table.addRecord({ values: { title: 'Observed row' } });
+     * disposable.dispose();
+     * ```
+     */
+    addEvent<T extends BaseEventName>(event: T, listener: (params: IBaseEventMap[T]) => void): IDisposable;
+    private _wrapTable;
+    private _resolveEvent;
+}
+export type CreateTableInput = ICreateTableInput;
+export type SearchTableInput = ISearchTableInput;
+export type CopyTableInput = ICopyTableInput;
+export type BaseSchemaSnapshot = IBaseSchemaSnapshot;

package/lib/types/facade/f-event.d.ts

@@ -0,0 +1,61 @@
+import type { BaseCellValue, ICommandInfo } from '@univerjs/core';
+import type { FTable } from './f-table';
+import type { FRecord } from './f-record';
+import type { FField } from './f-field';
+import type { FView } from './f-view';
+export declare const BaseEventName: {
+    readonly TableChanged: "TableChanged";
+    readonly FieldChanged: "FieldChanged";
+    readonly RecordChanged: "RecordChanged";
+    readonly CellValueChanged: "CellValueChanged";
+    readonly ViewChanged: "ViewChanged";
+};
+export type BaseEventName = typeof BaseEventName[keyof typeof BaseEventName];
+export interface IBaseTableChangedEvent {
+    type: 'created' | 'renamed' | 'deleted';
+    table: FTable | null;
+    tableId: string;
+    payload: Readonly<ICommandInfo>;
+}
+export interface IBaseFieldChangedEvent {
+    type: 'created' | 'updated' | 'typeChanged' | 'deleted' | 'moved';
+    table: FTable;
+    field: FField | null;
+    tableId: string;
+    fieldId: string;
+    payload: Readonly<ICommandInfo>;
+}
+export interface IBaseRecordChangedEvent {
+    type: 'created' | 'updated' | 'deleted' | 'duplicated' | 'moved';
+    table: FTable;
+    records: FRecord[];
+    tableId: string;
+    recordIds: string[];
+    payload: Readonly<ICommandInfo>;
+}
+export interface IBaseCellValueChangedEvent {
+    table: FTable;
+    tableId: string;
+    changes: Array<{
+        recordId: string;
+        fieldId: string;
+        value: BaseCellValue;
+    }>;
+    payload: Readonly<ICommandInfo>;
+}
+export interface IBaseViewChangedEvent {
+    type: 'created' | 'updated' | 'renamed' | 'deleted' | 'moved';
+    table: FTable;
+    view: FView | null;
+    tableId: string;
+    viewId: string;
+    payload: Readonly<ICommandInfo>;
+}
+export interface IBaseEventMap {
+    [BaseEventName.TableChanged]: IBaseTableChangedEvent;
+    [BaseEventName.FieldChanged]: IBaseFieldChangedEvent;
+    [BaseEventName.RecordChanged]: IBaseRecordChangedEvent;
+    [BaseEventName.CellValueChanged]: IBaseCellValueChangedEvent;
+    [BaseEventName.ViewChanged]: IBaseViewChangedEvent;
+}
+export type BaseEventMap = IBaseEventMap;

package/lib/types/facade/f-field.d.ts

@@ -0,0 +1,191 @@
+import type { BaseDataModel, ICommandService, IFieldSnapshot } from '@univerjs/core';
+/**
+ * Facade API object bound to a Base field.
+ *
+ * A Base field is equivalent to a column in a table.
+ * Field type and type-specific config live on the field snapshot. Cell values
+ * should reference field ids and should not duplicate field type as their
+ * source of truth.
+ *
+ * @example Update field metadata
+ * ```ts
+ * const field = table.getFieldByName('Status');
+ * if (field) {
+ *   await field.setName('Stage');
+ *   await field.setConfig({
+ *     options: [{ id: 'done', name: 'Done', color: 'green' }],
+ *   });
+ *   await field.update({ description: 'Workflow stage from server auth.' });
+ * }
+ * ```
+ */
+export declare class FField {
+    private readonly _base;
+    private readonly _tableId;
+    private readonly _fieldId;
+    private readonly _commandService;
+    constructor(_base: BaseDataModel, _tableId: string, _fieldId: string, _commandService: ICommandService);
+    /**
+     * Get the field id.
+     * @returns The field id.
+     * @example
+     * ```ts
+     * console.log(field.getId());
+     * ```
+     */
+    getId(): string;
+    /**
+     * Get the field snapshot.
+     * @returns The field snapshot.
+     * @example
+     * ```ts
+     * const rawField = field.getField();
+     * ```
+     */
+    getField(): IFieldSnapshot;
+    /**
+     * Get the field snapshot.
+     * @returns The field snapshot.
+     * @example
+     * ```ts
+     * const snapshot = field.getSnapshot();
+     * ```
+     */
+    getSnapshot(): IFieldSnapshot;
+    /**
+     * Get the field name.
+     * @returns The field name.
+     * @example
+     * ```ts
+     * console.log(field.getName());
+     * ```
+     */
+    getName(): string;
+    /**
+     * Get the field type.
+     * @returns The field type.
+     * @example
+     * ```ts
+     * console.log(field.getType());
+     * ```
+     */
+    getType(): IFieldSnapshot['type'];
+    /**
+     * Get the field configuration.
+     * @returns The field configuration.
+     * @example
+     * ```ts
+     * const config = field.getConfig();
+     * ```
+     */
+    getConfig(): IFieldSnapshot['config'];
+    /**
+     * Get the default value configured for this field.
+     * @returns The default value.
+     * @example
+     * ```ts
+     * const defaultValue = field.getDefaultValue();
+     * ```
+     */
+    getDefaultValue(): IFieldSnapshot['defaultValue'];
+    /**
+     * Get the field description.
+     * @returns The field description, if any.
+     * @example
+     * ```ts
+     * console.log(field.getDescription());
+     * ```
+     */
+    getDescription(): string | undefined;
+    /**
+     * Check whether this field is readonly.
+     * @returns True when the field is readonly.
+     * @example
+     * ```ts
+     * if (field.isReadonly()) return;
+     * ```
+     */
+    isReadonly(): boolean;
+    /**
+     * Rename this field.
+     * @param name The new field name.
+     * @example
+     * ```ts
+     * await field.setName('Priority');
+     * ```
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * Replace the field configuration.
+     *
+     * Config is type-specific. Keep select options, attachment restrictions,
+     * formula expressions, number/date formatting, and similar field metadata
+     * here so formulas and renderers can resolve behavior from the field.
+     *
+     * @param config The new field configuration. It replaces the current config.
+     * @example
+     * ```ts
+     * await formulaField.setConfig({
+     *   formula: '=SUM(table[Amount], Pricing[Tax])',
+     *   numberFormat: { type: 'currency', pattern: '"$"#,##0.00' },
+     * });
+     * ```
+     */
+    setConfig(config: IFieldSnapshot['config']): Promise<void>;
+    /**
+     * Set the default value for this field.
+     * @param defaultValue The new default value.
+     * @example
+     * ```ts
+     * await statusField.setDefaultValue('todo');
+     * ```
+     */
+    setDefaultValue(defaultValue: IFieldSnapshot['defaultValue']): Promise<void>;
+    /**
+     * Update this field.
+     * @param patch Partial field snapshot to merge into the field. Common
+     * fields are `name`, `config`, `defaultValue`, `description`, and
+     * `readonly`. Use `changeType()` when changing `type`.
+     * @example
+     * ```ts
+     * await field.update({ name: 'Score', description: 'Calculated score' });
+     * ```
+     */
+    update(patch: Partial<IFieldSnapshot>): Promise<void>;
+    /**
+     * Change this field type.
+     * @param input The target type and configuration. The `type` changes how
+     * existing and future cell values are interpreted, and `config` should be
+     * supplied for the new type.
+     * @example
+     * ```ts
+     * await field.changeType({ type: 'number', config: { decimalPlaces: 2 } });
+     * ```
+     */
+    changeType(input: Pick<IFieldSnapshot, 'type' | 'config'>): Promise<void>;
+    /**
+     * Delete this field.
+     * @example
+     * ```ts
+     * await field.delete();
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Move this field relative to another field.
+     * @param target Target position descriptor. Pass exactly one of
+     * `beforeFieldId` or `afterFieldId`.
+     * @param target.beforeFieldId Optional field id to move this field before.
+     * @param target.afterFieldId Optional field id to move this field after.
+     * @example
+     * ```ts
+     * await field.move({ beforeFieldId: 'status' });
+     * await field.move({ afterFieldId: 'title' });
+     * ```
+     */
+    move(target: {
+        beforeFieldId?: string;
+        afterFieldId?: string;
+    }): Promise<void>;
+    private _getField;
+}