@cruba/crubal 0.0.0-stage → 0.2.0

package/dist/src/views.d.ts

@@ -0,0 +1,216 @@
+import type { Access } from "./access.ts";
+import type { Dictionary } from "./defs.ts";
+import type { Json, JsonObject, Record } from "./model.ts";
+import { type RecordSet } from "./records.ts";
+export declare const AUDIENCES: readonly ["public", "member", "staff", "owner"];
+export type Slot = {
+    from: string;
+    to: string;
+    required: boolean;
+    line: number;
+};
+export type Shape = {
+    name: string;
+    slots: Slot[];
+    line: number;
+};
+export type Bucket = {
+    name: string;
+    values?: string[];
+    range?: [number, number];
+};
+export type Filter = {
+    name: string;
+    facet: string;
+    buckets?: Bucket[];
+    dependent: string[];
+    line: number;
+    bucketLines: number[];
+};
+export type View = {
+    name: string;
+    line: number;
+    level?: string;
+    wears: string[];
+    when?: string;
+    list?: string;
+    of?: string;
+    pin: string[];
+    hide: string[];
+    order: {
+        key: string;
+        dir: "after" | "before";
+    }[];
+    page: number;
+    shapes: string[];
+    filters: string[];
+    index: string[];
+    indexLine: number;
+    show: string;
+    fresh: string;
+    /** `administered`, `controlled`, `owned`, `relation <name>` or `none` (12.2); absent takes the default. */
+    partition?: string;
+    /** The dated version; a new version starts the view's stream over (12.6). */
+    version?: string;
+};
+export type RoleDef = {
+    name: string;
+    audience: string;
+    see: string[];
+    seeLine: number;
+    line: number;
+};
+/** A show rule with a `for`: it decides for the records its class, kind or level covers (12.4). */
+export type ShownFor = {
+    for: string;
+    audience: string;
+};
+export type ViewSet = {
+    shapes: Map<string, Shape>;
+    filters: Map<string, Filter>;
+    views: Map<string, View>;
+    roles: Map<string, RoleDef>;
+    shown: Map<string, string>;
+    shownFor: Map<string, ShownFor[]>;
+};
+/** Read shapes, filters, views (with a body), roles and `shown to` rules. */
+export declare function readViews(source: string): ViewSet;
+/**
+ * The lowest audience that may see a facet (12.4): a show rule whose `for` covers the record decides for it,
+ * a class over a kind or level, else the rule for everywhere; no rule, the public.
+ */
+export declare function shownAudience(set: Pick<ViewSet, "shown" | "shownFor">, facet: string, record?: Pick<Record, "kind" | "level" | "wears">, dict?: Pick<Dictionary, "kinds">): string | undefined;
+/** Can an audience see a facet, of this record when one is given? */
+export declare function visibleTo(set: Pick<ViewSet, "shown" | "shownFor">, facet: string, audience: string, record?: Pick<Record, "kind" | "level" | "wears">, dict?: Pick<Dictionary, "kinds">): boolean;
+export declare function checkViews(set: ViewSet, dict: Dictionary): void;
+export type ProjectOptions = {
+    audience?: string;
+    caller?: Record;
+    context?: Record;
+    picks?: {
+        [filter: string]: string[];
+    };
+    page?: number;
+    /** Access (chapter 14) for partitioned views: the index serves a caller only the rows their edges match. */
+    access?: Access;
+    /** Only these records: a projector rebuilding the rows a write made stale (12.6) asks for them alone. */
+    only?: string[];
+    /**
+     * Every row in one pass, no page and no counts: a projector publishing the view (12.6) wants the rows,
+     * and a page at a time would select and count the whole view once per page (ME: 197 pages of 9,437 units).
+     */
+    all?: boolean;
+};
+export type Counts = {
+    [filter: string]: {
+        [bucket: string]: number;
+    };
+};
+/** Dependent counts (12.3): filter → bucket → dependent facet → value → count. */
+export type Nested = {
+    [filter: string]: {
+        [bucket: string]: {
+            [dependent: string]: {
+                [value: string]: number;
+            };
+        };
+    };
+};
+export type Projection = {
+    rows: JsonObject[];
+    records: string[];
+    counts: Counts;
+    nested?: Nested;
+    pages: number;
+    indexable: boolean;
+};
+/** One entry of a view's projection stream (12.6, 12.7). */
+export type StreamEntry = {
+    projection: string;
+    audience: string;
+    seq: number;
+    record: string;
+    row?: JsonObject;
+    buckets?: JsonObject;
+    sort?: string[];
+    pin?: number;
+    removed?: true;
+    reset?: true;
+};
+/** The shapes the core defines (12.1, 12.5): the portable one, and structured data for the public. */
+export declare const CORE_SHAPES: string[];
+/** A view's partition: what it declares, else `controlled` above member and `none` otherwise (12.2). */
+export declare function partitionOf(v: View): string;
+export declare class Views {
+    readonly dict: Dictionary;
+    readonly set: ViewSet;
+    private records;
+    private engine;
+    /** Over a record set of the caller's (a store's working set), or an empty memory set to `put` into. */
+    constructor(dict: Dictionary, set: ViewSet, records?: RecordSet);
+    put(r: Record): void;
+    private effective;
+    /** The classes a record wears, those of the records above it included (5.5). */
+    private wearsOf;
+    private below;
+    /** The values an address reads, as a list: own values, or a lower level's (`unit::price`). */
+    private valuesAt;
+    /** Is a value fit for this audience's eyes? New, unknown and held values never reach the public. */
+    private fit;
+    private canSee;
+    private slot;
+    /**
+     * What a condition reads of a record (6.3): the envelope under `crubal:`, and bare `id` and `status`
+     * too unless a facet of that name holds a value, which then wins.
+     */
+    private conditionValues;
+    /** The values of the view's order keys as text, and the pin position: what an index orders rows by (12.7). */
+    sortOf(v: View, r: Record): {
+        sort: string[];
+        pin?: number;
+    };
+    /** The buckets a record falls into, per filter of the view (12.6): what an index counts from. */
+    bucketsFor(v: View, r: Record): JsonObject;
+    /** Dependent counts (12.3) over records already narrowed by the other filters. */
+    nestedCounts(v: View, pool: (f: string) => Record[]): Nested;
+    /** Does a view select this record (its own tests, before curation and the shape's required slots)? */
+    private selects;
+    /** The records a list holds, in its order (12.2): the links in its `crubal:items`. */
+    private listed;
+    private inBucket;
+    private bucketsOf;
+    /** The records a view selects, curated and ordered, before filters and paging. */
+    select(v: View, opts?: ProjectOptions): Record[];
+    /** The roles whose `see` a slot needs above member (12.6 role marks): none when members may see it. */
+    private marksFor;
+    /** A view's projection for an audience (or a caller), with filter counts and a page. */
+    project(name: string, opts?: ProjectOptions): Projection;
+    /** One record in one shape: a core shape's object, or the shape's slots with their role marks. */
+    private shaped;
+    /** A nested view's rows for a page record (12.1, 12.2 `of`): every page, in the view's order. */
+    private nestedRows;
+    /**
+     * Structured data (12.5): schema.org JSON-LD for the public from the kind's type per level (11.2) and
+     * each facet's `same-as` in the schema prefix; nothing for any other audience.
+     */
+    jsonld(r: Record, audience?: string): JsonObject | undefined;
+    private streams;
+    /** A view's version, as its stream names it. */
+    versionOf(name: string): string;
+    /** A new version of a view: its stream starts over at the next publish (12.6). */
+    revise(name: string, version: string): void;
+    /**
+     * The projection stream (12.6): the entries since the last publish of this view for this audience, one
+     * per row that is new or changed, and one removal per row that left. Numbered per view and audience; a
+     * new version of the view starts over at 1, its first entry marked `reset`.
+     */
+    stream(name: string, opts?: Omit<ProjectOptions, "page" | "picks">): StreamEntry[];
+    /** The current version's entries after `seq`, for an index resuming from its cursor (12.6.2). */
+    entriesSince(name: string, seq: number, audience?: string): StreamEntry[];
+    /** The portable shape (12.1): key, label, type and value for every value the audience may see. */
+    portable(r: Record, audience?: string, caller?: Record): Json[];
+    /** The keys a view reads (12.6), with level prefixes kept. */
+    readSet(name: string): Set<string>;
+    /** Which of a view's rows a write makes stale: the written record, or what reads it through. */
+    staleAfter(name: string, write: Record): string[];
+}