@loradb/lora-graphql 0.16.2

package/dist/analyze/cypher-check.d.ts

@@ -0,0 +1,8 @@
+import { LoraDriver } from '../driver.js';
+import { GraphModel } from '../model/types.js';
+export interface CypherFinding {
+    type: string;
+    field: string;
+    message: string;
+}
+export declare function checkCypherFields(driver: LoraDriver, model: GraphModel): Promise<CypherFinding[]>;

package/dist/analyze/diff.d.ts

@@ -0,0 +1,32 @@
+import { DocumentNode } from 'graphql';
+import { ModelOptions } from '../model/build.js';
+import { SchemaRequirement } from './indexes.js';
+export interface ApiChange {
+    /** graphql-js change type, e.g. `FIELD_REMOVED`. */
+    type: string;
+    description: string;
+}
+export interface SchemaDiff {
+    database: {
+        create: SchemaRequirement[];
+        drop: SchemaRequirement[];
+        /**
+         * Statements in the order to run them. Drops and data migrations are
+         * destructive: review them before running.
+         */
+        statements: Array<{
+            text: string;
+            destructive: boolean;
+            reason: string;
+        }>;
+    };
+    api: {
+        /** Changes that break existing clients. */
+        breaking: ApiChange[];
+        /** Changes that may change behaviour for existing clients. */
+        dangerous: ApiChange[];
+    };
+    /** Consequences worth a human look, e.g. a rename kept by @alias. */
+    notes: string[];
+}
+export declare function diffSchemas(before: string | DocumentNode, after: string | DocumentNode, options?: ModelOptions): SchemaDiff;

package/dist/analyze/indexes.d.ts

@@ -0,0 +1,61 @@
+import { GraphModel, IndexKind, ScalarType } from '../model/types.js';
+export type SchemaRequirement = {
+    kind: "constraint";
+    constraint: "NODE_KEY" | "UNIQUE" | "NOT_NULL";
+    name: string;
+    label: string;
+    property: string;
+    /** Why the library needs it, e.g. `Festival.key is the @key`. */
+    reason: string;
+} | {
+    kind: "index";
+    index: IndexKind;
+    name: string;
+    label: string;
+    property: string;
+    reason: string;
+} | {
+    /** Queried by name, so matched by name. */
+    kind: "fulltext";
+    name: string;
+    label: string;
+    properties: string[];
+    analyzer: "STANDARD" | "SIMPLE";
+    reason: string;
+} | {
+    /** Queried by name, so matched by name. */
+    kind: "vector";
+    name: string;
+    label: string;
+    property: string;
+    dimensions: number;
+    similarity: "COSINE" | "EUCLIDEAN";
+    reason: string;
+};
+/**
+ * Types a RANGE index must not be inferred for. LoraDB keeps durations out
+ * of its sorted index (they have no total order); other temporals are
+ * indexed by the instant they denote (E17).
+ */
+export declare const RANGE_UNINDEXABLE: Set<ScalarType>;
+/**
+ * Derive every constraint and index the model's API needs.
+ *
+ * - `@key` → node key constraint (unique + present); it also serves
+ *   exact-match, range and ordered scans, so no extra index.
+ * - `@unique` → uniqueness constraint (backed by a RANGE index).
+ * - `@sortable` on a non-null field → existence constraint: keyset
+ *   pagination may then bound the scan with `>=` without losing nulls.
+ * - `EQ` / `IN` → nothing: LoraDB builds exact-match indexes lazily.
+ * - `LT` / `LTE` / `GT` / `GTE` or `@sortable` → RANGE.
+ * - `CONTAINS` / `STARTS_WITH` / `ENDS_WITH` → TEXT.
+ * - `WITHIN_BBOX` / `DISTANCE` on a Point → POINT.
+ * - `@index(kind:)` → that index.
+ */
+export declare function inferRequirements(model: GraphModel): SchemaRequirement[];
+/** A stable identity: equal ids need no change between two models. */
+export declare function requirementId(r: SchemaRequirement): string;
+/** One line for humans, e.g. `RANGE index on :Festival(name)`. */
+export declare function describeRequirement(r: SchemaRequirement): string;
+/** The DDL statement that creates a requirement, idempotently. */
+export declare function requirementDdl(r: SchemaRequirement): string;

package/dist/analyze/lint.d.ts

@@ -0,0 +1,6 @@
+import { GraphModel, ModelWarning } from '../model/types.js';
+export interface LintOptions {
+    /** Statistics are loaded: relationship degrees are known. */
+    statistics?: boolean;
+}
+export declare function lintModel(model: GraphModel, options?: LintOptions): ModelWarning[];

package/dist/analyze/plans.d.ts

@@ -0,0 +1,31 @@
+import { LoraDriver, QueryPlan, Statement } from '../driver.js';
+import { CompiledRead } from '../compile/read.js';
+export interface PlanFinding {
+    rule: "full-scan" | "mutating-read" | "result-columns" | "scan-expand" | "row-budget";
+    message: string;
+    statement: string;
+}
+export interface PlanReport {
+    statement: Statement;
+    plan: QueryPlan;
+    /** Operator names from root to leaves, depth first. */
+    operators: string[];
+    /**
+     * The engine's largest row estimate among the statement's scans and
+     * seeks (from graph statistics), or null when it has none. A scan that
+     * streams in index order under a LIMIT reads fewer rows than this.
+     */
+    estimatedRows: number | null;
+    findings: PlanFinding[];
+}
+export declare function checkPlans(driver: LoraDriver, compiled: CompiledRead, options?: {
+    rowBudget?: number;
+}): Promise<PlanReport[]>;
+/**
+ * Expansions that start from a full scan: an `Expand` whose source is a
+ * `NodeByLabelScan`, or a `NodeScan` with nothing below it that binds the
+ * node. A key test in the same pattern as the expansion plans this way,
+ * and the statement then walks every relationship of the type. Statements
+ * that start from keys (every mutation statement) must have none.
+ */
+export declare function scanExpands(statement: Statement, plan: QueryPlan): PlanFinding[];

package/dist/analyze/statistics.d.ts

@@ -0,0 +1,19 @@
+import { LoraDriver } from '../driver.js';
+import { GraphModel } from '../model/types.js';
+export interface DegreeStats {
+    sampled: number;
+    mean: number;
+    median: number;
+    p99: number;
+    max: number;
+}
+export interface Statistics {
+    /** Node count per @node type. */
+    nodes: Record<string, number>;
+    /** Degree per list relationship, keyed `Type.field`. */
+    degrees: Record<string, DegreeStats>;
+}
+export declare function analyze(driver: LoraDriver, model: GraphModel, options?: {
+    sample?: number;
+    timeoutMs?: number;
+}): Promise<Statistics>;

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+interface Io {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+export declare function main(argv: string[], io?: Io): Promise<number>;
+export {};