@getaster/data 0.0.0-stage → 0.1.0-preview.1

package/dist/scope/scope.d.ts

@@ -0,0 +1,181 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { DataContext } from "../context.ts";
+import type { Criteria } from "../criteria/ast.ts";
+import type { EdmType, EntityType, Field, Value } from "../schema/model.ts";
+/**
+ * What a component makes visible to its page: named signals, and the entity
+ * type behind any that hold a record, so paths into them are typed.
+ */
+export interface Publication {
+    readonly values: Readonly<Record<string, ReadonlySignal<unknown>>>;
+    readonly types?: Readonly<Record<string, EntityType>>;
+    /** For a name that holds a record: its fields hidden from the caller (`StoredRecord.hidden`). */
+    readonly hidden?: Readonly<Record<string, ReadonlySignal<ReadonlySet<string>>>>;
+}
+/**
+ * A condition over the scope. Criteria name paths (`people.selected.name`)
+ * where a query names properties; a bare path means "is true", anywhere in
+ * the tree.
+ */
+export type Condition = Criteria | string | {
+    readonly op: "and" | "or";
+    readonly args: readonly Condition[];
+} | {
+    readonly op: "not";
+    readonly arg: Condition;
+};
+/** `condition` as plain criteria, bare paths spelled out. */
+export declare function toCriteria(condition: Condition): Criteria;
+/** A rule with the reason shown when it applies. */
+export interface Ruled {
+    readonly when: Condition;
+    readonly reason?: string;
+}
+export interface StateRules {
+    /** Visible only while this holds. */
+    readonly visible?: Condition | Ruled;
+    /** Enabled only while this holds. */
+    readonly enabled?: Condition | Ruled;
+    /** Read-only while this holds. */
+    readonly readOnly?: Condition | Ruled;
+    /** Required while this holds. */
+    readonly required?: Condition | Ruled;
+}
+export type Effect = keyof StateRules;
+export interface FieldState {
+    readonly visible: boolean;
+    readonly enabled: boolean;
+    readonly readOnly: boolean;
+    readonly required: boolean;
+    /** Why each effect isn't at its default, when a reason was given. */
+    readonly reasons: Readonly<Partial<Record<Effect, string>>>;
+}
+export declare const DEFAULT_STATE: FieldState;
+/**
+ * One case of a derived value (`scope.select`): when `when` holds (or always,
+ * without one), the value is the literal `value`, the value at `path`, or
+ * `template` rendered over the scope.
+ */
+export type Case = {
+    readonly when?: Condition;
+} & ({
+    readonly value: Value;
+} | {
+    readonly path: string;
+} | {
+    readonly template: string;
+} | {
+    readonly aggregate: "min" | "max" | "average";
+    readonly path: string;
+    readonly field: string;
+});
+/** A derived signal owns any related-list requests; dispose it when its consumer goes away. */
+export interface SelectedValue extends ReadonlySignal<unknown> {
+    dispose(): void;
+}
+/** Navigations a path may follow from a published record: `task.values.project.lead.name` follows two. */
+export declare const MAX_HOPS = 3;
+/** A published name: its record type and fields' CSDL types, when the publication gives them. */
+export interface ScopeName {
+    readonly type?: string;
+    readonly fields?: Readonly<Record<string, EdmType>>;
+}
+/** Every published key's names (`scope.schema()`). Plain data. */
+export type ScopeSchema = Readonly<Record<string, Readonly<Record<string, ScopeName>>>>;
+/** One step of `explain`: a rule, what it read and what it decided. */
+export interface Explanation {
+    readonly effect: Effect | "derived";
+    readonly rule: Condition;
+    readonly reason?: string;
+    readonly holds: boolean;
+    readonly reads: Readonly<Record<string, unknown>>;
+    /** Paths it read as unknown: fields hidden on their record. */
+    readonly unknown?: readonly string[];
+    /** Derived cases, the selected case (zero-based), and its current result. */
+    readonly cases?: readonly Case[];
+    readonly matched?: number;
+    readonly value?: unknown;
+    readonly overridden?: boolean;
+    readonly current?: unknown;
+    readonly error?: string;
+}
+/**
+ * A page's published state, by key. Components publish under a key; rules and
+ * other components read by path without a reference to the publisher.
+ *
+ * Invariants: a key has one publisher per scope; reading an unpublished key
+ * gives `undefined` and follows it once it's published; a child scope's keys
+ * shadow its parent's.
+ */
+export declare class PageScope {
+    #private;
+    readonly parent: PageScope | undefined;
+    /** The clock relative dates in rules resolve against; a child scope has its parent's. */
+    readonly now: () => number;
+    /** Where paths through a navigation find the related record; a child scope has its parent's. */
+    readonly ctx: DataContext | undefined;
+    constructor(parent?: PageScope, options?: {
+        now?: () => number;
+        ctx?: DataContext;
+    });
+    child(): PageScope;
+    /** Publishes under `key`; returns the function that withdraws it. */
+    publish(key: string, publication: Publication): () => void;
+    /** The published keys, nearest scope first. */
+    keys(): string[];
+    /**
+     * What can be read, typed: each published key's names, with the record
+     * type and its fields' CSDL types where the publication gives them. For
+     * rule builders and tools, to offer and check paths before a rule exists.
+     */
+    schema(): ScopeSchema;
+    /**
+     * Why a path can't be read, or `undefined` if it can: an unpublished key,
+     * an unknown name, a property the record type lacks, a step past a field,
+     * or more than `MAX_HOPS` navigations.
+     */
+    check(path: string): string | undefined;
+    /**
+     * A path's value: the key's signal, then properties of the value it holds.
+     * From a typed record, a step that names a single-valued navigation reads
+     * the related record from the store through `ctx` (fetching it if it isn't
+     * loaded), so `task.values.project.name` follows the task's project; it's
+     * `undefined` until the record arrives and `null` with no related record.
+     */
+    value(path: string): ReadonlySignal<unknown>;
+    /**
+     * A derived value: the first case whose rule holds gives it, and a case
+     * without a rule is the default. `undefined` when no case applies, and
+     * while a path it has to read is `undefined` (an unpublished key, a
+     * related record still loading), so nothing is decided on missing data.
+     */
+    select(cases: readonly Case[], target?: string): SelectedValue;
+    /**
+     * The field a path reads, when its publication gives the record type and
+     * the path ends on a property of that record or of a record reached
+     * through its navigations. Other paths are untyped. A property the record
+     * type doesn't have is an error, not a silent null.
+     */
+    field(path: string): Field | undefined;
+    /**
+     * Whether `rule` holds, as a signal. A field hidden on its record is
+     * unknown to the rule, not null: a test of it is unknown, and a rule holds
+     * only when it's true.
+     */
+    when(rule: Condition): ReadonlySignal<boolean>;
+    /** Conservative action availability: every referenced value must be available. */
+    available(rule: Condition): ReadonlySignal<boolean>;
+    /** Invalid publication/property paths in a rule, without evaluating it. */
+    checkRule(rule: Condition): string[];
+    /** The state of `target` from its rules; registered for `explain` and `readers`. */
+    state(target: string, rules: StateRules, options?: {
+        availability?: boolean;
+    }): ReadonlySignal<FieldState>;
+    /** Every rule registered for `target`, with what it read and decided now. */
+    explain(target: string): Explanation[];
+    /** The targets whose rules read `path` or anything under it. */
+    readers(path: string): {
+        target: string;
+        effect: Effect;
+    }[];
+}