@trdrs/quickcharts 1.0.0

package/dist/resources-Ch8eA1Mw.d.ts

@@ -0,0 +1,228 @@
+declare const DRAWING_CONTEXT_VERSION = 1;
+type DrawingContextKind = 'chart-local' | 'layout-shared' | 'symbol-global';
+/** One chart of one layout, on one symbol. */
+interface ChartLocalDrawingContext {
+    version: typeof DRAWING_CONTEXT_VERSION;
+    kind: 'chart-local';
+    /** The host's stable identity for the layout the chart is tiled in. */
+    layoutId: string;
+    /** The chart's stable identity WITHIN that layout, so the document is found again after a
+     *  reload; a per-mount instance id would key a document nothing could ever read back. */
+    chartId: string;
+    symbol: string;
+}
+/** Every chart of one layout, on one symbol. */
+interface LayoutSharedDrawingContext {
+    version: typeof DRAWING_CONTEXT_VERSION;
+    kind: 'layout-shared';
+    layoutId: string;
+    symbol: string;
+}
+/** Every chart the host mounts, on one symbol. */
+interface SymbolGlobalDrawingContext {
+    version: typeof DRAWING_CONTEXT_VERSION;
+    kind: 'symbol-global';
+    symbol: string;
+}
+type DrawingResourceContext = ChartLocalDrawingContext | LayoutSharedDrawingContext | SymbolGlobalDrawingContext;
+/** The drawings document format. Bumping this is the only reason a reader ever branches. */
+declare const DRAWING_DOCUMENT_VERSION = 1;
+/** One drawing in a document. The ENVELOPE is structured so a restore is validated without parsing
+ *  the drawing itself: the id is stable for the drawing's life, `source` names what owns it (the
+ *  main series, or an indicator's own source), `pane` names where it is drawn, and `type` is its
+ *  tool. `state` is the drawing's own serialized form and is opaque to the document, the store and
+ *  the transport. */
+interface DrawingEntry {
+    id: string;
+    /** The owning source: `main` for the chart's main series, else an indicator instance's id. */
+    source: string;
+    /** The pane the drawing is drawn in: `main` for the price pane, else the pane owner's id. */
+    pane: string;
+    type: string;
+    /** Opaque: nothing between the layer and the backend reads it. */
+    state: unknown;
+    /** The group this drawing belongs to, when it belongs to one. */
+    group?: string;
+}
+/** A group of drawings. Membership is ORDERED and holds drawing ids, so a group survives a round
+ *  trip with its order intact rather than being rebuilt from however a document happened to list
+ *  its entries. */
+interface DrawingGroup {
+    id: string;
+    name?: string;
+    members: readonly string[];
+}
+/** A deletion, kept. A document that listed only what survives lets a concurrent save, a reconnect
+ *  or a reload resurrect what the trader deleted: the other side still holds the row and a merge
+ *  takes it back. A tombstone says the deletion happened, and at which document revision, so the
+ *  merge drops it instead. */
+interface DrawingTombstone {
+    kind: 'drawing' | 'group';
+    id: string;
+    /** The document revision the deletion was stamped at. */
+    at: number;
+}
+/** One context's drawings document. `revision` is the DOCUMENT's own counter, which orders
+ *  tombstones and detects a stale apply; it is not the store's `ResourceRef.revision`, which stays
+ *  opaque and is the store's alone. */
+interface DrawingsBody {
+    version: typeof DRAWING_DOCUMENT_VERSION;
+    context: DrawingResourceContext;
+    revision: number;
+    entries: readonly DrawingEntry[];
+    groups: readonly DrawingGroup[];
+    tombstones: readonly DrawingTombstone[];
+}
+/** The canonical key for a drawing-resource context: equal contexts key equally, and no two
+ *  different contexts collide. The parts join on an escaped null, which no symbol, layout id or
+ *  chart id carries, so a symbol ending in a separator cannot spell another context's key. The
+ *  kind and version lead, so a later kind is a different key rather than a widened old one. */
+declare function drawingContextKey(context: DrawingResourceContext): string;
+/** Whether two contexts name the same document. */
+declare const sameDrawingContext: (a: DrawingResourceContext, b: DrawingResourceContext) => boolean;
+/** A document with nothing in it, at revision 0: what a context that has never been written reads
+ *  as, so every caller works over a document rather than over a null. */
+declare function emptyDrawingDocument(context: DrawingResourceContext): DrawingsBody;
+/** The entries a document actually holds: nothing buried, no duplicate id, and no membership of a
+ *  group that is gone (the drawing survives, its grouping does not). */
+declare function liveDrawingEntries(document: DrawingsBody): DrawingEntry[];
+/** The groups a document actually holds: nothing buried, no duplicate id, and no member that is
+ *  buried or absent, so a group never names a drawing that is not there. */
+declare function liveDrawingGroups(document: DrawingsBody): DrawingGroup[];
+/** Replace what a document holds and stamp the difference. Every id the document held and the next
+ *  state does not is buried at the new revision; every id that arrives is kept in the order it
+ *  arrives in. One verb, one revision bump, so a save can never write entries at one revision and
+ *  groups at another. */
+declare function reviseDrawingDocument(document: DrawingsBody, next: {
+    entries?: readonly DrawingEntry[];
+    groups?: readonly DrawingGroup[];
+}): DrawingsBody;
+/** Merge the document another surface wrote first with this surface's own. The stored rows win by
+ *  identity and keep the stored order, because they are what everyone else can already see; rows
+ *  only this surface holds follow, because they are work the other surface never saw. Every
+ *  deletion either side made survives the merge. The result's revision is past both, so the write
+ *  that carries it is the newer document by either side's counter. */
+declare function mergeDrawingDocuments(stored: DrawingsBody, mine: DrawingsBody): DrawingsBody;
+/** Read whatever a transport handed back as a document for this context. TOTAL: a null, a string, a
+ *  wrong version, a junk row or a whole junk body reads as the empty document, never a throw, so a
+ *  host can hand the chart what its backend returned without guarding it first. The context is the
+ *  caller's, not the payload's: a document is identified by where it was read from, and a body
+ *  claiming another context is not merged into this one. */
+declare function parseDrawingDocument(value: unknown, context: DrawingResourceContext): DrawingsBody;
+
+/** A resource's identity plus the exact version this reader saw. A write quotes it back. */
+interface ResourceRef {
+    id: string;
+    /** Opaque to the chart: minted by the store, compared only for equality. */
+    revision: string;
+}
+/** What a write did. `ok` carries the ref the store now holds (and, where the store computes one,
+ *  the resulting metadata); `conflict` carries the ref that beat this write, so a caller can reload
+ *  and re-decide; `not-found` means the id is gone. */
+type WriteOutcome<T = void> = {
+    kind: 'ok';
+    ref: ResourceRef;
+    value?: T;
+} | {
+    kind: 'conflict';
+    current: ResourceRef;
+} | {
+    kind: 'not-found';
+};
+/** One family of resources. `Meta` is the listing row a picker shows without fetching content
+ *  (it carries the row's ref, so a picker can delete or open a row without a second read); `Body`
+ *  is the stored document. */
+interface ResourceStore<Meta, Body> {
+    /** Listing rows, metadata only. */
+    list(signal?: AbortSignal): Promise<Meta[]>;
+    /** The stored document and the revision it was read at, or null when the id is unknown. */
+    load(id: string, signal?: AbortSignal): Promise<{
+        ref: ResourceRef;
+        body: Body;
+    } | null>;
+    /** Store a new document. The store mints the id; a create conflicts only where the store keys a
+     *  document by identity and one already stands there (a drawings context that holds a document, a
+     *  name already taken), and then it answers the ref that stands. */
+    create(body: Body, signal?: AbortSignal): Promise<WriteOutcome<Meta>>;
+    /** Replace the document at `ref.id`, but only while it still stands at `ref.revision`. */
+    update(ref: ResourceRef, body: Body, signal?: AbortSignal): Promise<WriteOutcome<Meta>>;
+    /** Delete the document at `ref.id`, but only while it still stands at `ref.revision`. */
+    remove(ref: ResourceRef, signal?: AbortSignal): Promise<WriteOutcome<void>>;
+}
+/** A saved chart's listing row. */
+interface ChartMeta extends ResourceRef {
+    name: string;
+    symbol: string;
+    timeframe: string;
+    /** Last save, ms since epoch (server-stamped by real backends). */
+    updatedAt: number;
+}
+/** A saved chart. `content` is the chart's own serialized state, opaque to the store. */
+interface ChartBody {
+    name: string;
+    symbol: string;
+    timeframe: string;
+    content: string;
+}
+/** A saved multi-chart layout's listing row. `symbol` is the active chart's market as the chart
+ *  writes it (`symbolNames(...).mark`, such as `BTCUSDC`) and `timeframe` its timeframe token, both
+ *  as they stood at the last save, so a listing can say what each layout shows without opening it. A
+ *  store that does not keep them, or a layout saved before they were stated, leaves them out. */
+interface LayoutMeta extends ResourceRef {
+    name: string;
+    symbol?: string;
+    timeframe?: string;
+    updatedAt: number;
+}
+/** A saved multi-chart layout. `content` is the arrangement's serialized state, opaque to the store.
+ *  The widget states the listing's `symbol` and `timeframe` on every save; they are display text and
+ *  play no part in restoring the layout. */
+interface LayoutBody {
+    name: string;
+    symbol?: string;
+    timeframe?: string;
+    content: string;
+}
+/** A drawings document's listing row. A context holds at most one, so `list` returns zero rows or
+ *  one, and the ref is the store's handle on it. */
+interface DrawingsMeta extends ResourceRef {
+    updatedAt: number;
+}
+type TemplateKind = 'study' | 'drawing' | 'palette';
+/** A named template's listing row. `tool` scopes DRAWING templates to their tool (a trend-line
+ *  template is meaningless on a rectangle); study and palette templates carry no tool. */
+interface TemplateMeta extends ResourceRef {
+    name: string;
+    tool?: string;
+    updatedAt: number;
+}
+interface TemplateBody {
+    name: string;
+    tool?: string;
+    content: string;
+}
+/** The adapter a host implements: four resource families over one revisioned contract. Viewer
+ *  settings are deliberately absent; they belong to `ChartStorage`. */
+interface ChartSaveLoadAdapter {
+    charts: ResourceStore<ChartMeta, ChartBody>;
+    layouts: ResourceStore<LayoutMeta, LayoutBody>;
+    /** The store for one drawing-resource context. Calling with an equal context returns an
+     *  equivalent store; `drawingContextKey` is the canonical way to compare two. */
+    drawings(context: DrawingResourceContext): ResourceStore<DrawingsMeta, DrawingsBody>;
+    templates(kind: TemplateKind): ResourceStore<TemplateMeta, TemplateBody>;
+}
+/** The error every store rejects with when its signal aborts. `name` is 'AbortError', which is what
+ *  callers branch on, and what `DOMException` uses, so a host may reject with either. */
+declare class ResourceAbortError extends Error {
+    readonly name = "AbortError";
+    constructor(message?: string);
+}
+/** Options for {@link memorySaveLoadAdapter}: a clock, so a test can pin `updatedAt`. */
+interface MemoryResourcesOptions {
+    now?: () => number;
+}
+/** An in-memory {@link ChartSaveLoadAdapter}. Each drawing context and each template kind gets its
+ *  own store, created on first ask and kept, so two calls for one context see the same document. */
+declare function memorySaveLoadAdapter(options?: MemoryResourcesOptions): ChartSaveLoadAdapter;
+
+export { type ChartSaveLoadAdapter as C, DRAWING_CONTEXT_VERSION as D, type LayoutSharedDrawingContext as L, type MemoryResourcesOptions as M, type ResourceRef as R, type SymbolGlobalDrawingContext as S, type TemplateBody as T, type WriteOutcome as W, type ChartLocalDrawingContext as a, DRAWING_DOCUMENT_VERSION as b, type DrawingContextKind as c, type DrawingEntry as d, type DrawingGroup as e, type DrawingResourceContext as f, type DrawingTombstone as g, type DrawingsBody as h, type ResourceStore as i, type TemplateMeta as j, drawingContextKey as k, emptyDrawingDocument as l, liveDrawingEntries as m, liveDrawingGroups as n, mergeDrawingDocuments as o, parseDrawingDocument as p, type ChartMeta as q, reviseDrawingDocument as r, sameDrawingContext as s, type ChartBody as t, type DrawingsMeta as u, type LayoutMeta as v, type LayoutBody as w, ResourceAbortError as x, type TemplateKind as y, memorySaveLoadAdapter as z };