@ahoo-wang/wow-view-engine 9.2.0-rc.0

package/dist/runtime/viewEngine.d.ts

@@ -0,0 +1,292 @@
+import { Issue, RuntimeLimits, ViewConfig, ViewDefinition, ViewInstance, ViewAudience, ViewInstanceSummary, ViewPreferences, ViewScope } from '../model/index.js';
+import { FieldKindRegistry } from '../filter/index.js';
+import { ViewPermissions, ViewStore } from '../store/ViewStore.js';
+import { RuntimeEnvironment } from './environment.js';
+import { OptionSource, ViewSource } from './source.js';
+import { AnyViewRuntime, CreateInput, OpenOptions, RuntimeFor, ViewRuntime } from './viewRuntimeTypes.js';
+import { WriteState } from './write.js';
+import { ConflictChoice, WriteTarget } from './writeLedger.js';
+import { ViewChangeListener } from './viewChanges.js';
+import { EngineResources } from './resources.js';
+/**
+ * One thing a host registers (host-integration.md 4): a definition, and
+ * where its data comes from. A board's definition has no source — it
+ * queries nothing of its own.
+ */
+export interface ViewResource {
+    definition: ViewDefinition;
+    /** Where a data definition's rows come from; a board has none. */
+    source?: ViewSource;
+}
+export interface ViewEngineOptions {
+    /** What the host registers: each definition, with its data's source. */
+    resources: readonly ViewResource[];
+    store: ViewStore;
+    /** Remote candidates of `reference` fields, by the same key. */
+    resolveOptions?(key: string): OptionSource;
+    kinds?: FieldKindRegistry;
+    /**
+     * How the definitions' keys (`text(key)`) are said in the language the
+     * engine starts in, for a host with no Provider; a Provider says them in
+     * its own (`setText`). Keys stay in the definitions and in every
+     * runtime's state, and are read into words as the engine hands them out,
+     * so a change of language redraws what is open rather than rebuilding
+     * anything (host-integration.md 3.1, D2). Left out, a key reads as
+     * itself until a language is set.
+     */
+    text?(key: string): string | undefined;
+    /**
+     * The host's budgets over `DEFAULT_RUNTIME_LIMITS`: what is left out keeps
+     * its default. The source budgets (`maxPageSize`, `maxPageWindow`,
+     * `maxAnalysisRows`, `maxQueryFilterNodes`, `maxFilterValues`) are said by a source's descriptor
+     * where it has one, and one given here only lowers it — so leave them out
+     * unless the engine should ask for less than the server admits
+     * (capabilities.md 4.5).
+     */
+    limits?: Partial<RuntimeLimits>;
+    environment?: RuntimeEnvironment;
+    /** Idempotency keys; overridden in tests to keep them readable. */
+    newId?(): string;
+    /**
+     * Findings with no caller to reject and nothing thrown behind them: a
+     * definition's admission, a list entry that was dropped, a change
+     * listener that threw. Failures — a query, a store call, an export, a
+     * render — go to `environment.onError` instead (D40).
+     *
+     * Left out, a development build (`NODE_ENV` of `development`) writes them
+     * to the console, grouped by resource, each with how to fix it; any other
+     * build drops them.
+     */
+    onIssue?(issue: Issue): void;
+}
+/**
+ * What a definition's list is right now: every view that could be read, and
+ * the reason the rest could not. The declared system views are always in
+ * `items`; `failed` names the store's failure when the saved ones are not.
+ */
+export interface ViewListing {
+    items: ViewInstanceSummary[];
+    failed: Issue | null;
+}
+/**
+ * The registry and the command entry point: definitions in, runtimes and
+ * writes out.
+ *
+ * What the commands stand on lives beside this file, one concern each: the
+ * definition registry (`definitions.ts`), the permission checks
+ * (`permissions.ts`), the preference cache (`preferences.ts`), the summary
+ * cache (`summaries.ts`), the open views (`openRuntimes.ts`), how one runtime
+ * is assembled (`runtimeFactory.ts`) and the write ledger
+ * (`writeLedger.ts`). What is left here is the command surface itself:
+ * admission, then one dispatch.
+ *
+ * Every write goes through one path, so the default UI and a hand-built one
+ * behave the same, and every non-success outcome lands in the same three
+ * recovery actions: `retryWrite`, `abandonWrite`, `resolveConflict`.
+ *
+ * A dashboard is opened by the same commands as a data view. What differs is
+ * that it composes other instances, so the engine hands it the two things it
+ * cannot reach itself: how to read a referenced instance, and how to build a
+ * child runtime for it.
+ *
+ * Construct it; do not extend it. Its base class is how the file is split,
+ * not an extension point.
+ *
+ * @sealed
+ */
+export declare class ViewEngine extends EngineResources {
+    /**
+     * The host's store as the engine reads it: every view it hands back is
+     * read into the form this engine writes on its way in (`readingStore`,
+     * AGENTS.md's stored-data exception), and nothing past it migrates.
+     */
+    readonly store: ViewStore;
+    readonly environment: RuntimeEnvironment;
+    readonly kinds: FieldKindRegistry;
+    readonly limits: RuntimeLimits;
+    private readonly options;
+    private readonly runner;
+    /** What each source admits; see `capabilities.ts`. */
+    private readonly capabilities;
+    private readonly registry;
+    protected readonly registered: ReadonlyMap<string, ViewDefinition>;
+    private readonly guard;
+    private readonly preferenceCache;
+    private readonly runtimes;
+    private readonly factory;
+    /** Every write that left, and every outcome not yet settled. */
+    private readonly ledger;
+    /** Saving a dashboard panel's view as a view of its own; see `panelViews.ts`. */
+    private readonly panelViews;
+    /** Who is told that a definition's list has changed; see `subscribe`. */
+    private readonly changes;
+    /** The last summary seen of each instance; see `summaries.ts`. */
+    private readonly summaries;
+    /** Where each reader last read each board; see `tabMemory.ts`. */
+    private readonly tabs;
+    constructor(options: ViewEngineOptions);
+    /** What `validateDefinition` said about one definition, for a host to show. */
+    definitionIssues(definitionId: string): Issue[];
+    permissions(definitionId: string): ViewPermissions;
+    /**
+     * Code-declared system views first, then whatever the store holds. An id in
+     * the reserved namespace is dropped and reported: only a definition may
+     * declare one.
+     */
+    list(definitionId: string): Promise<ViewListing>;
+    /**
+     * Told whenever a write changes what a definition's list holds — a view
+     * created, saved, renamed or deleted, the ledger's retries and overwrites
+     * included. Returns the way to stop listening.
+     *
+     * The engine is the one place that knows when a write lands, so it says so
+     * rather than leaving every caller to remember (D15).
+     */
+    subscribe(listener: ViewChangeListener): () => void;
+    preferences(definitionId: string): Promise<ViewPreferences>;
+    /** Opens a saved view, or a code-declared one without touching the store. */
+    open(instanceId: string, options?: OpenOptions): Promise<AnyViewRuntime>;
+    /** One instance, from the definition's code or from the store. */
+    private readInstance;
+    /**
+     * An unsaved view. It carries a complete config from the start, produced by
+     * `defaultRecordConfig`, `defaultAnalysisConfig` or `emptyDashboardConfig`,
+     * and executes at once so the user sees data rather than an empty frame.
+     *
+     * No permission is asked here: nothing is written until the first save,
+     * and `save` asks then. A reader who may create nothing still drills from
+     * a chart into the records behind a bar — a view that is only looked at
+     * costs the store nothing (H1).
+     */
+    create<C extends ViewConfig>(definitionId: string, input: CreateInput<C>): RuntimeFor<C>;
+    /** First save creates, later saves overwrite. Both need a clean draft. */
+    save(runtime: ViewRuntime): Promise<ViewInstance>;
+    /**
+     * A copy under a new title and scope; the source runtime is untouched.
+     * `scope: 'system'` makes it a stored system view, which needs
+     * `editSystem` (D81).
+     */
+    saveAs(runtime: ViewRuntime, input: {
+        title: string;
+        scope: ViewScope;
+    }): Promise<ViewInstance>;
+    /**
+     * Saves a view a dashboard owns as a view of its own (「另存为视图」, D22 C)
+     * and points the panel at it (`PanelViews`). A view the board does not
+     * own, or a panel it lacks, is refused (`dashboard.panel.not-owned`).
+     */
+    saveOwnedView(dashboard: ViewRuntime, panelId: string, input: {
+        title: string;
+        scope: ViewScope;
+    }): Promise<ViewInstance>;
+    /**
+     * Copies the saved view a dashboard panel shows into another audience and
+     * points the panel at the copy (「复制为共享视图并替换」, D22 B,
+     * `PanelViews`): a shared board standing on someone's personal view is
+     * blank for every other reader, and the copy is what they can open. A
+     * panel showing no saved view this reader has open is refused
+     * (`dashboard.panel.not-referenced`).
+     */
+    copyPanelView(dashboard: ViewRuntime, panelId: string, input: {
+        title: string;
+        scope: ViewScope;
+    }): Promise<ViewInstance>;
+    /**
+     * 「发布为系统视图」 (D81): a copy of the saved view `id`, as it is saved —
+     * not the draft of an open one — under its own title, created as a stored
+     * system view. The view it was made from is left as it is; the copy is
+     * the one everyone sees, and the one an admin edits from then on.
+     *
+     * Asked before anything is sent: `editSystem` (`view.create.forbidden`),
+     * and the config's size, as for any create. The manager offers it on
+     * personal and shared rows only; a system view is published already.
+     */
+    publishAsSystem(id: string): Promise<ViewInstance>;
+    /** Renaming carries no config, so a draft with errors does not block it. */
+    rename(id: string, title: string): Promise<ViewInstance>;
+    /**
+     * 设为共享／设为个人 (D18 item 10): the saved view moves to `audience` in
+     * place, id kept, through the store's optional `changeAudience` — a store
+     * without it is refused here (`view.changeAudience.unsupported`), and the
+     * manager offers no such button. Like a rename it carries no config, so a
+     * draft with errors does not block it, and every open view of the
+     * instance moves to the new baseline.
+     *
+     * Asked before anything is sent: the instance permission and the create
+     * permission of the audience it goes to (`instanceAbilities`). Asked for
+     * the audience it already has, it answers the view as it is and writes
+     * nothing.
+     *
+     * A board shared over a personal view is not refused, as a shared board's
+     * save is not (`validateDashboard`, D22 B): the panel is blank for other
+     * readers and says so (`dashboard.panel.scope-too-narrow`, a warning the
+     * open board takes up as it moves). The one refusal between the two is the
+     * store's: a view a shared board shows is not made personal (`INVALID`).
+     */
+    changeAudience(id: string, audience: ViewAudience): Promise<ViewInstance>;
+    delete(id: string): Promise<void>;
+    /** Submits the full visible order, with the revision it was read at. */
+    reorder(definitionId: string, order: string[]): Promise<ViewPreferences>;
+    setDefault(definitionId: string, instanceId: string | null): Promise<ViewPreferences>;
+    /**
+     * Whether this user's analyses of the definition run again on their own as
+     * they are edited (D20 改了就跑). A personal preference like the order and
+     * the default, kept beside them; no permission gates it, because it
+     * changes nothing anyone else sees.
+     */
+    setAutoRun(definitionId: string, autoRun: boolean): Promise<ViewPreferences>;
+    /**
+     * Remembers the tab this reader last read a dashboard on (D22 E), kept
+     * with their other preferences for the board's definition and read back
+     * by `open`. A convenience: it never rejects and never leaves an outcome
+     * behind (`TabMemory`).
+     */
+    rememberTab(definitionId: string, instanceId: string, tabId: string): Promise<void>;
+    /**
+     * The effective default: an explicit id, else the stored one when it still
+     * exists, else the first of the ordered list, which is usually the first
+     * system view.
+     */
+    resolveDefault(summaries: readonly ViewInstanceSummary[], preferences: ViewPreferences, explicit?: string): string | null;
+    /** Writes still waiting for a decision, by handle id. */
+    pendingWrites(): ReadonlyMap<string, WriteState>;
+    /** Replays the original intent under its original `requestId`. */
+    retryWrite(target: WriteTarget): Promise<ViewInstance | ViewPreferences | void>;
+    /** Drops the outcome and keeps the draft; a later save is a new intent. */
+    abandonWrite(target: WriteTarget): void;
+    /**
+     * `reload` takes the server's state, losing the draft; `overwrite` replays
+     * the original intent against the revision the conflict reported, which is a
+     * new logical write and so takes a new `requestId`.
+     */
+    resolveConflict(target: WriteTarget, choice: ConflictChoice): Promise<ViewInstance | ViewPreferences | void>;
+    /** Open runtimes, for a workbench that tracks its own tabs. */
+    openRuntimes(): readonly ViewRuntime[];
+    /**
+     * Closes one open view: disposes it and drops it from the registry.
+     *
+     * A caller that only calls `runtime.dispose()` leaves the engine holding a
+     * dead runtime, which then answers `locate` with a revision nobody can write
+     * against, so this is the way to let one go.
+     */
+    close(runtime: ViewRuntime): void;
+    dispose(): void;
+    private attach;
+    private build;
+    private writePreferences;
+    /**
+     * What the ledger reaches back for. A confirmed write settles in the ledger,
+     * but it also moves what only the engine holds — the summary and preference
+     * caches, and the open runtimes of the instance it touched — so the engine
+     * lends those out as closures rather than as members of its own surface.
+     */
+    private ledgerHost;
+    /**
+     * What a command needs about an instance it was given only the id of: the
+     * revision to write against, the definition whose list it belongs to, and
+     * the open view it came through, from an open view, the last list, or the
+     * store.
+     */
+    private locate;
+}
+//# sourceMappingURL=viewEngine.d.ts.map

package/dist/runtime/viewEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewEngine.d.ts","sourceRoot":"","sources":["../../src/runtime/viewEngine.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAEV,eAAe,EACf,SAAS,EACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAEX,WAAW,EACX,UAAU,EACV,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAUxE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,cAAc,CAAC;IAC3B,kEAAkE;IAClE,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB,gEAAgE;IAChE,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC;IAC3C,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B;;;;;;;;OAQG;IACH,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,mEAAmE;IACnE,KAAK,CAAC,IAAI,MAAM,CAAC;IACjB;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IACxE,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAIlB;gBAES,OAAO,EAAE,iBAAiB;IAyDtC,+EAA+E;IAC/E,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,KAAK,EAAE;IAI/C,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe;IAIlD;;;;OAIG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAwBtD;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAI7C,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE,6EAA6E;IACvE,IAAI,CACR,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,cAAc,CAAC;IA8B1B,kEAAkE;YACpD,YAAY;IAO1B;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,SAAS,UAAU,EACzB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GACpB,UAAU,CAAC,CAAC,CAAC;IAuBhB,0EAA0E;IACpE,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IA8BvD;;;;OAIG;IACG,MAAM,CACV,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,GACzC,OAAO,CAAC,YAAY,CAAC;IAuBxB;;;;OAIG;IACH,aAAa,CACX,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,GACzC,OAAO,CAAC,YAAY,CAAC;IASxB;;;;;;;OAOG;IACH,aAAa,CACX,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,GACzC,OAAO,CAAC,YAAY,CAAC;IASxB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKlD,4EAA4E;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAO9D;;;;;;;;;;;;;;;;;;OAkBG;IACG,cAAc,CAClB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,YAAY,CAAC;IAkBlB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,wEAAwE;IAClE,OAAO,CACX,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,eAAe,CAAC;IASrB,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,eAAe,CAAC;IAY3B;;;;;OAKG;IACG,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,eAAe,CAAC;IAK3B;;;;;OAKG;IACH,WAAW,CACT,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;OAIG;IACH,cAAc,CACZ,SAAS,EAAE,SAAS,mBAAmB,EAAE,EACzC,WAAW,EAAE,eAAe,EAC5B,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI;IAIhB,yDAAyD;IACzD,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC;IAIhD,kEAAkE;IAC5D,UAAU,CACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,GAAG,eAAe,GAAG,IAAI,CAAC;IAIjD,2EAA2E;IAC3E,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIvC;;;;OAIG;IACG,eAAe,CACnB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,YAAY,GAAG,eAAe,GAAG,IAAI,CAAC;IAIjD,+DAA+D;IAC/D,YAAY,IAAI,SAAS,WAAW,EAAE;IAItC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIjC,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,MAAM;IAiBd,OAAO,CAAC,KAAK;YAWC,gBAAgB;IAQ9B;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAmBlB;;;;;OAKG;YACW,MAAM;CA0BrB"}

package/dist/runtime/viewRuntime.d.ts

@@ -0,0 +1,199 @@
+import { DataViewConfig, FieldDefinition, FilterTree, Issue, RecordPageTarget, RuntimeLimits, ViewInstance } from '../model/index.js';
+import { FieldKindRegistry } from '../filter/index.js';
+import { RuntimeEnvironment, ViewErrorKind } from './environment.js';
+import { FailureReporter } from './failures.js';
+import { RuntimeStore } from './runtimeStore.js';
+import { SourceFailure } from './sourceReason.js';
+import { OptionSource, ProjectedView } from './source.js';
+import { KernelContext } from './execute.js';
+import { ValueCandidateSource } from './valueCandidates.js';
+import { WriteState } from './write.js';
+import { DefinitionFor, ManagedViewRuntime, ViewRuntimeOptions, ViewRuntimeState } from './viewRuntimeTypes.js';
+/**
+ * The runtime of a data view: an Analysis view as it is, and the shared
+ * half of a Record view (`RecordDataViewRuntime`).
+ *
+ * It owns no persistence: saving is a command of `ViewEngine`, which calls
+ * `markSaved` once the store has confirmed it.
+ *
+ * The store half of it — the snapshot, the subscribers, the refresh timer and
+ * dirty-against-saved — is `RuntimeStore`, which the dashboard runtime holds
+ * one of as well; what is left here is what it means to be a data view: ask,
+ * run, land. What only a Record view has — a page, a selection, an export, a
+ * record read whole — is its subclass's, reached through four hooks
+ * (`startOver`, `pageNow`, `settle`, `holds`) rather than kind checks here.
+ */
+export declare class DataViewRuntime<C extends DataViewConfig = DataViewConfig> implements ManagedViewRuntime<C> {
+    readonly id: string;
+    readonly kind: C['kind'];
+    readonly kinds: FieldKindRegistry;
+    readonly environment: RuntimeEnvironment;
+    protected readonly store: RuntimeStore<ViewRuntimeState<C>>;
+    protected readonly context: KernelContext;
+    private readonly runner;
+    private readonly resolveOptions;
+    private readonly autoRefresh;
+    /** What the source admits, followed while open; see `renarrow`. */
+    private readonly capabilities;
+    private readonly stopFollowing;
+    /**
+     * Why the definition cannot run at all under the source's current
+     * descriptor, said at the head of every admission until it changes again.
+     */
+    private refusal;
+    /** Whether a host lets the view refresh itself (`setAutoRefresh`). */
+    private refreshing;
+    /** The one timer behind 「改了就跑」, stopped whenever nothing is due. */
+    private readonly autoTimer;
+    private readonly candidates;
+    private injectedScope;
+    /**
+     * Whether `applied` merged with the scope passed admission. `apply` and
+     * `setScopeFilter` only promote what did, so this is false only for the
+     * config a runtime opened on, and it keeps `refresh` and `page` from running
+     * what `apply` would refuse.
+     */
+    protected appliedAdmitted: boolean;
+    private requestSeq;
+    constructor(options: ViewRuntimeOptions<C>);
+    /**
+     * When the answer on screen stops being true of its own accord: a metric
+     * card over a trend skipped the period under way when it was asked, and
+     * that period has ended by then (`periodRollover`). The chart read is the
+     * draft's — how the rows are looked at is the draft's to say (D20) — over
+     * the config that ran them. `null` for anything else.
+     */
+    rolloverAt(): number | null;
+    /** The definition in force: the declared one as the source narrows it now. */
+    get definition(): DefinitionFor<C>;
+    /** The budgets in force: the host's, and the source's where it says them. */
+    get limits(): RuntimeLimits;
+    get disposed(): boolean;
+    /** See `ViewRuntime.refusedScope`; the store keeps it. */
+    get refusedScope(): Issue[];
+    /** The snapshot the store holds; every command reads it and patches it back. */
+    protected get state(): ViewRuntimeState<C>;
+    get fields(): readonly FieldDefinition[];
+    /** The injected condition in force; see `ViewRuntime.scopeFilter`. */
+    get scopeFilter(): FilterTree | null;
+    getSnapshot(): ViewRuntimeState<C>;
+    subscribe(listener: () => void): () => void;
+    optionSource(remote: string): OptionSource | null;
+    valueCandidates(field: string): ValueCandidateSource | null;
+    edit(patch: Partial<C>): void;
+    apply(): void;
+    /**
+     * How `draft` lands when it changes only how the rows on screen are drawn,
+     * or `null` when it is a new question and runs whole. A Record view
+     * answers for its columns and its summary row (`restyledOnly`); an
+     * analysis has nothing of the kind.
+     */
+    protected restyle(draft: C): (() => void) | null;
+    /** Discards the edits and re-runs what was saved; see `RuntimeStore.revert`. */
+    revert(): void;
+    setAutoApply(on: boolean): void;
+    /**
+     * Arms the auto-apply timer while the draft is due to run on its own and
+     * stops it otherwise. Re-arming on every edit is what merges a burst of
+     * edits into one query: the timer restarts from the last one.
+     */
+    private syncAutoApply;
+    /**
+     * Re-runs what was applied, which was admitted before it ran. An invalid
+     * draft therefore does not block it: the editor may be mid-edit and wrong,
+     * while the results on screen answer a question that was legal when asked.
+     * Auto-refresh still pauses on an invalid draft — it is one of the reasons
+     * `syncTimer` below holds the timer — but a user pressing Refresh has asked
+     * for exactly this.
+     */
+    refresh(): void;
+    setEditing(active: boolean): void;
+    setAutoRefresh(on: boolean): void;
+    setScopeFilter(tree: FilterTree | null): Issue[];
+    /** A record or an analysis config means the same thing in every scope. */
+    issuesAt(): Issue[];
+    /** Called by `ViewEngine` once a write has been confirmed by the store. */
+    markSaved(instance: ViewInstance): void;
+    moveBaseline(stored: ViewInstance): void;
+    /** Replaces the draft with the store's state, used by "reload" on a conflict. */
+    adoptSaved(instance: ViewInstance): void;
+    /** Called by `ViewEngine` with the outcome of a write it dispatched. */
+    setWrite(write: WriteState | null): void;
+    dispose(): void;
+    /** See `ViewRuntime.unavailable`. */
+    unavailable(): Issue[];
+    /** See `ViewRuntime.removeUnavailable`. */
+    removeUnavailable(): void;
+    /**
+     * Takes the source's current descriptor: the definition and the limits
+     * narrowed again, the draft and the applied config judged again. A config
+     * still admitted keeps its result on screen — only what the editors offer
+     * moves; one that is not waits to be fixed like any error, and nothing
+     * more is sent for it (capabilities.md 6「版本变了」, Q2).
+     */
+    private renarrow;
+    /**
+     * The configs the view holds, read under the paths a new narrowing
+     * renames aliases to (#3519): what it applied, what it drafts and what
+     * it was saved as, so a view asks by the names the source answers by.
+     */
+    private renameFields;
+    private unavailableOf;
+    /**
+     * What a new question starts from, merged into the state it is put in
+     * force with — by `apply`, and by a new injected scope. An analysis has
+     * nothing to reset; a Record view goes back to its first page and lets
+     * its selection go.
+     */
+    protected startOver(): Partial<ViewRuntimeState<C>>;
+    /** The page a query asks for; an analysis has none. */
+    protected pageNow(): RecordPageTarget | undefined;
+    /**
+     * What else a landed answer changes, or `null` to ask again instead — a
+     * Record view whose page the result shrank out from under asks for the
+     * last page there is. `keepSelection` is whether the query was a refresh.
+     */
+    protected settle(data: ProjectedView, keepSelection: boolean): Partial<ViewRuntimeState<C>> | null;
+    /** A reason of the kind's own to hold the refresh timer. */
+    protected holds(): boolean;
+    /**
+     * Admission of a config together with the scope it would run under. Every
+     * judgement in this class goes through here, so the draft, the applied
+     * config and an injected condition are all held to one rule.
+     */
+    private admit;
+    protected execute(options: {
+        keepSelection: boolean;
+        /** When the question was first asked, for a page asked again. */
+        askedAt?: number;
+        /**
+         * What is fetched, when it is less than the whole config: the summary
+         * row alone over the rows on screen (`restyle`). The whole query when
+         * left out.
+         */
+        fetch?: (config: C, controller: AbortController) => Promise<ProjectedView>;
+        /**
+         * Asked without the query turning `loading`: the rows on screen stay the
+         * answer while the rest arrives, so nothing says 「正在查询」 over them
+         * or draws the table as waiting (the summary row alone, `restyle`).
+         */
+        quiet?: boolean;
+    }): void;
+    private onSuccess;
+    private onFailure;
+    private failed;
+    /**
+     * Whether a kind takes a failure back and asks again instead: a Record
+     * view whose cursor the source no longer reads starts over from the
+     * first page, once. Nothing else does.
+     */
+    protected recovers(failure: SourceFailure): boolean;
+    /**
+     * Tells the host of a failure of this view's (D40), saying which view:
+     * its definition, its saved id as it is at the moment of the failure, and
+     * the runtime it failed in.
+     */
+    protected reporter(kind: ViewErrorKind): FailureReporter;
+    private isCurrent;
+}
+//# sourceMappingURL=viewRuntime.d.ts.map

package/dist/runtime/viewRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewRuntime.d.ts","sourceRoot":"","sources":["../../src/runtime/viewRuntime.ts"],"names":[],"mappings":"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"}