@skygraph/core 0.0.0-placeholder.0 → 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,144 @@
+import { C as Core, W as WriteEvent, M as Middleware } from './types-B-rKQJ4R.cjs';
+export { N as NextFn, a as WriteSource } from './types-B-rKQJ4R.cjs';
+export { MeasureCache, MeasureCacheEvent, MeasureCacheListener, MeasureCacheOptions, VirtualEngine, VirtualEngineEvent, VirtualEngineListener, VirtualEngineOptions, VirtualItem, VirtualRange, createMeasureCache, createVirtual } from './virtual.cjs';
+export { FieldMeta, FieldMetaExtensions, FieldOptions, FormEngine, FormListOperation, FormOptions, FormState, GetFieldValue, Rule, RuleFn, RuleObject, ValidationMode, ValidationResult, createForm } from './form.cjs';
+export { AABB, Anchor, AnchorId, AnchorPolicy, BezierPathOptions, EdgeEndpoint, EdgeId, EdgeInit, GraphEdge, GraphEngine, GraphEngineOptions, GraphNode, GraphState, NodeId, NodeInit, NodeTransform, NodeUpdate, OBB, Outline, Point, RouteOrthogonalOptions, Side, aabbFromOBB, createGraph, getBezierPath, nearestSide, obbContainsPoint, obbCorners, pointsToPath, pointsToRoundedPath, routeOrthogonal } from './graph.cjs';
+export { AdvancedFilter, AggregateFn, AggregateType, ColumnAggregate, ColumnFilter, FilterFn, FilterOperator, RowId, SortConfig, SortDirection, TableEngine, TableGroup, TableOptions, TableState, computeAggregate, createTable, matchesColumnFilter, matchesOperator, resolveOperator } from './table.cjs';
+export { TreeEngine, TreeEngineOptions, TreeFieldNames, TreeKey, TreeNodeData, TreeState, createTree } from './tree.cjs';
+export { Assignment as CalendarAssignment, AssignmentStatus as CalendarAssignmentStatus, AvailabilityRule as CalendarAvailabilityRule, Conflict as CalendarConflict, ConflictReason as CalendarConflictReason, DayOfWeek as CalendarDayOfWeek, DetectConflictsOptions as CalendarDetectConflictsOptions, CalendarEngine, CalendarEngineOptions, Resource as CalendarResource, CalendarScale, CalendarState, createCalendar, detectConflicts, isAvailable } from './calendar.cjs';
+
+declare function createCore(): Core;
+
+interface LoggerOptions {
+    filter?: (event: WriteEvent) => boolean;
+    log?: (message: string, event: WriteEvent) => void;
+}
+declare function loggerMiddleware(options?: LoggerOptions): Middleware;
+
+/**
+ * Prevents writes to specified path prefixes.
+ * Useful for making parts of the store read-only.
+ */
+declare function freezeMiddleware(frozenPaths: string[]): Middleware;
+
+interface PersistenceOptions {
+    key?: string;
+    paths?: string[];
+    storage?: {
+        getItem(key: string): string | null;
+        setItem(key: string, value: string): void;
+    };
+    debounce?: number;
+}
+/**
+ * Persists selected paths to a storage backend (localStorage by default).
+ * Debounced to avoid excessive writes.
+ */
+declare function persistenceMiddleware(options?: PersistenceOptions): Middleware;
+
+type Validator = (event: WriteEvent) => boolean | string;
+interface ValidationMiddlewareOptions {
+    validators: Record<string, Validator>;
+    onReject?: (event: WriteEvent, reason: string) => void;
+}
+/**
+ * Validates writes against a map of path -> validator.
+ * If the validator returns false or a string (error message),
+ * the write is rejected and onReject is called (if provided).
+ */
+declare function validationMiddleware(optionsOrValidators: ValidationMiddlewareOptions | Record<string, Validator>): Middleware;
+
+interface HistoryEntry {
+    timestamp: number;
+    patches: ReadonlyArray<{
+        path: string;
+        value: unknown;
+        oldValue: unknown;
+    }>;
+}
+interface HistoryPlugin {
+    readonly entries: ReadonlyArray<HistoryEntry>;
+    readonly cursor: number;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    undo(): void;
+    redo(): void;
+    jumpTo(index: number): void;
+    clear(): void;
+    destroy(): void;
+}
+interface HistoryOptions {
+    maxEntries?: number;
+    /** Group multiple writes within this window (ms) into a single entry */
+    groupWindow?: number;
+    filter?: (event: WriteEvent) => boolean;
+}
+declare function createHistory(core: Core, options?: HistoryOptions): HistoryPlugin;
+
+/**
+ * Utility types for path-based type inference.
+ * These provide compile-time type safety over the untyped Core runtime.
+ */
+type Primitive = string | number | boolean | null | undefined;
+/**
+ * Extracts dot-notation paths from a nested object type (max 3 levels deep).
+ * Example: Path<{user: {name: string}}> = "user" | "user.name"
+ */
+type Path<T> = T extends Primitive ? never : {
+    [K in keyof T & string]: T[K] extends Primitive ? K : T[K] extends Record<string, unknown> ? K | `${K}.${keyof T[K] & string}` | {
+        [L in keyof T[K] & string]: T[K][L] extends Record<string, unknown> ? `${K}.${L}.${keyof T[K][L] & string}` : never;
+    }[keyof T[K] & string] : K;
+}[keyof T & string];
+/**
+ * Resolves the value type at a given dot-notation path (max 3 levels).
+ */
+type PathValue<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends keyof T[K] ? T[K][Rest] : Rest extends `${infer L}.${infer M}` ? L extends keyof T[K] ? M extends keyof T[K][L] ? T[K][L][M] : unknown : unknown : unknown : unknown : unknown;
+/**
+ * Type-safe wrapper over Core.
+ * Compile-time only — runtime behavior is identical to Core.
+ */
+interface TypedCore<T> {
+    get<K extends Path<T>>(path: K): PathValue<T, K>;
+    set<K extends Path<T>>(path: K, value: PathValue<T, K>): void;
+    subscribe<K extends Path<T>>(path: K, cb: (value: PathValue<T, K>) => void): () => void;
+    batch(fn: () => void): void;
+    transaction(fn: () => void): void;
+    computed<K extends Path<T>>(target: K, deps: Path<T>[], fn: (...values: unknown[]) => PathValue<T, K>): void;
+    /** Access the untyped core underneath */
+    raw: Core;
+}
+/**
+ * Creates a type-safe wrapper around an existing Core instance.
+ * No runtime overhead — just type narrowing.
+ */
+declare function createTypedCore<T>(core: Core): TypedCore<T>;
+
+/**
+ * Engine path namespace registry
+ *
+ * Every engine that stores state in the Core store under a `$`-prefixed
+ * namespace MUST register its prefix here. This prevents two engines from
+ * silently colliding on the same root path (e.g. two engines both writing
+ * under `$meta.`).
+ *
+ * Rules:
+ *   1. Prefixes MUST start with `$` and end with `.`.
+ *   2. Prefixes MUST be unique across all engines.
+ *   3. An engine MUST use `reservedPrefix(name)` at module load so
+ *      collisions surface at import time during dev/test.
+ *   4. User data MUST NOT live under `$` prefixes — reserve them for engines.
+ */
+/**
+ * Reserve (or look up) a prefix for an engine. Throws synchronously if the
+ * same prefix is already owned by a different engine.
+ */
+declare function reservePrefix(engine: string, prefix: string): string;
+/** Snapshot of registered engine prefixes (debug / introspection). */
+declare function listReservedPrefixes(): ReadonlyMap<string, string>;
+declare const FORM_META_PREFIX: string;
+declare const TABLE_PREFIX: string;
+declare const TREE_PREFIX: string;
+declare const GRAPH_PREFIX: string;
+declare const CALENDAR_PREFIX: string;
+
+export { CALENDAR_PREFIX, Core, FORM_META_PREFIX, GRAPH_PREFIX, type HistoryEntry, type HistoryOptions, type HistoryPlugin, Middleware, type Path, type PathValue, TABLE_PREFIX, TREE_PREFIX, type TypedCore, type ValidationMiddlewareOptions, type Validator, WriteEvent, createCore, createHistory, createTypedCore, freezeMiddleware, listReservedPrefixes, loggerMiddleware, persistenceMiddleware, reservePrefix, validationMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import { C as Core, W as WriteEvent, M as Middleware } from './types-B-rKQJ4R.js';
+export { N as NextFn, a as WriteSource } from './types-B-rKQJ4R.js';
+export { MeasureCache, MeasureCacheEvent, MeasureCacheListener, MeasureCacheOptions, VirtualEngine, VirtualEngineEvent, VirtualEngineListener, VirtualEngineOptions, VirtualItem, VirtualRange, createMeasureCache, createVirtual } from './virtual.js';
+export { FieldMeta, FieldMetaExtensions, FieldOptions, FormEngine, FormListOperation, FormOptions, FormState, GetFieldValue, Rule, RuleFn, RuleObject, ValidationMode, ValidationResult, createForm } from './form.js';
+export { AABB, Anchor, AnchorId, AnchorPolicy, BezierPathOptions, EdgeEndpoint, EdgeId, EdgeInit, GraphEdge, GraphEngine, GraphEngineOptions, GraphNode, GraphState, NodeId, NodeInit, NodeTransform, NodeUpdate, OBB, Outline, Point, RouteOrthogonalOptions, Side, aabbFromOBB, createGraph, getBezierPath, nearestSide, obbContainsPoint, obbCorners, pointsToPath, pointsToRoundedPath, routeOrthogonal } from './graph.js';
+export { AdvancedFilter, AggregateFn, AggregateType, ColumnAggregate, ColumnFilter, FilterFn, FilterOperator, RowId, SortConfig, SortDirection, TableEngine, TableGroup, TableOptions, TableState, computeAggregate, createTable, matchesColumnFilter, matchesOperator, resolveOperator } from './table.js';
+export { TreeEngine, TreeEngineOptions, TreeFieldNames, TreeKey, TreeNodeData, TreeState, createTree } from './tree.js';
+export { Assignment as CalendarAssignment, AssignmentStatus as CalendarAssignmentStatus, AvailabilityRule as CalendarAvailabilityRule, Conflict as CalendarConflict, ConflictReason as CalendarConflictReason, DayOfWeek as CalendarDayOfWeek, DetectConflictsOptions as CalendarDetectConflictsOptions, CalendarEngine, CalendarEngineOptions, Resource as CalendarResource, CalendarScale, CalendarState, createCalendar, detectConflicts, isAvailable } from './calendar.js';
+
+declare function createCore(): Core;
+
+interface LoggerOptions {
+    filter?: (event: WriteEvent) => boolean;
+    log?: (message: string, event: WriteEvent) => void;
+}
+declare function loggerMiddleware(options?: LoggerOptions): Middleware;
+
+/**
+ * Prevents writes to specified path prefixes.
+ * Useful for making parts of the store read-only.
+ */
+declare function freezeMiddleware(frozenPaths: string[]): Middleware;
+
+interface PersistenceOptions {
+    key?: string;
+    paths?: string[];
+    storage?: {
+        getItem(key: string): string | null;
+        setItem(key: string, value: string): void;
+    };
+    debounce?: number;
+}
+/**
+ * Persists selected paths to a storage backend (localStorage by default).
+ * Debounced to avoid excessive writes.
+ */
+declare function persistenceMiddleware(options?: PersistenceOptions): Middleware;
+
+type Validator = (event: WriteEvent) => boolean | string;
+interface ValidationMiddlewareOptions {
+    validators: Record<string, Validator>;
+    onReject?: (event: WriteEvent, reason: string) => void;
+}
+/**
+ * Validates writes against a map of path -> validator.
+ * If the validator returns false or a string (error message),
+ * the write is rejected and onReject is called (if provided).
+ */
+declare function validationMiddleware(optionsOrValidators: ValidationMiddlewareOptions | Record<string, Validator>): Middleware;
+
+interface HistoryEntry {
+    timestamp: number;
+    patches: ReadonlyArray<{
+        path: string;
+        value: unknown;
+        oldValue: unknown;
+    }>;
+}
+interface HistoryPlugin {
+    readonly entries: ReadonlyArray<HistoryEntry>;
+    readonly cursor: number;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    undo(): void;
+    redo(): void;
+    jumpTo(index: number): void;
+    clear(): void;
+    destroy(): void;
+}
+interface HistoryOptions {
+    maxEntries?: number;
+    /** Group multiple writes within this window (ms) into a single entry */
+    groupWindow?: number;
+    filter?: (event: WriteEvent) => boolean;
+}
+declare function createHistory(core: Core, options?: HistoryOptions): HistoryPlugin;
+
+/**
+ * Utility types for path-based type inference.
+ * These provide compile-time type safety over the untyped Core runtime.
+ */
+type Primitive = string | number | boolean | null | undefined;
+/**
+ * Extracts dot-notation paths from a nested object type (max 3 levels deep).
+ * Example: Path<{user: {name: string}}> = "user" | "user.name"
+ */
+type Path<T> = T extends Primitive ? never : {
+    [K in keyof T & string]: T[K] extends Primitive ? K : T[K] extends Record<string, unknown> ? K | `${K}.${keyof T[K] & string}` | {
+        [L in keyof T[K] & string]: T[K][L] extends Record<string, unknown> ? `${K}.${L}.${keyof T[K][L] & string}` : never;
+    }[keyof T[K] & string] : K;
+}[keyof T & string];
+/**
+ * Resolves the value type at a given dot-notation path (max 3 levels).
+ */
+type PathValue<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends keyof T[K] ? T[K][Rest] : Rest extends `${infer L}.${infer M}` ? L extends keyof T[K] ? M extends keyof T[K][L] ? T[K][L][M] : unknown : unknown : unknown : unknown : unknown;
+/**
+ * Type-safe wrapper over Core.
+ * Compile-time only — runtime behavior is identical to Core.
+ */
+interface TypedCore<T> {
+    get<K extends Path<T>>(path: K): PathValue<T, K>;
+    set<K extends Path<T>>(path: K, value: PathValue<T, K>): void;
+    subscribe<K extends Path<T>>(path: K, cb: (value: PathValue<T, K>) => void): () => void;
+    batch(fn: () => void): void;
+    transaction(fn: () => void): void;
+    computed<K extends Path<T>>(target: K, deps: Path<T>[], fn: (...values: unknown[]) => PathValue<T, K>): void;
+    /** Access the untyped core underneath */
+    raw: Core;
+}
+/**
+ * Creates a type-safe wrapper around an existing Core instance.
+ * No runtime overhead — just type narrowing.
+ */
+declare function createTypedCore<T>(core: Core): TypedCore<T>;
+
+/**
+ * Engine path namespace registry
+ *
+ * Every engine that stores state in the Core store under a `$`-prefixed
+ * namespace MUST register its prefix here. This prevents two engines from
+ * silently colliding on the same root path (e.g. two engines both writing
+ * under `$meta.`).
+ *
+ * Rules:
+ *   1. Prefixes MUST start with `$` and end with `.`.
+ *   2. Prefixes MUST be unique across all engines.
+ *   3. An engine MUST use `reservedPrefix(name)` at module load so
+ *      collisions surface at import time during dev/test.
+ *   4. User data MUST NOT live under `$` prefixes — reserve them for engines.
+ */
+/**
+ * Reserve (or look up) a prefix for an engine. Throws synchronously if the
+ * same prefix is already owned by a different engine.
+ */
+declare function reservePrefix(engine: string, prefix: string): string;
+/** Snapshot of registered engine prefixes (debug / introspection). */
+declare function listReservedPrefixes(): ReadonlyMap<string, string>;
+declare const FORM_META_PREFIX: string;
+declare const TABLE_PREFIX: string;
+declare const TREE_PREFIX: string;
+declare const GRAPH_PREFIX: string;
+declare const CALENDAR_PREFIX: string;
+
+export { CALENDAR_PREFIX, Core, FORM_META_PREFIX, GRAPH_PREFIX, type HistoryEntry, type HistoryOptions, type HistoryPlugin, Middleware, type Path, type PathValue, TABLE_PREFIX, TREE_PREFIX, type TypedCore, type ValidationMiddlewareOptions, type Validator, WriteEvent, createCore, createHistory, createTypedCore, freezeMiddleware, listReservedPrefixes, loggerMiddleware, persistenceMiddleware, reservePrefix, validationMiddleware };