@abloatai/ablo 0.36.0 → 0.37.1

package/dist/utils/mobxSetup.js

@@ -1,330 +0,0 @@
-/**
- * Wires a model instance into MobX so its schema-defined fields become
- * observable and its mutations are tracked. This module reads the property
- * metadata generated from a schema and applies the matching MobX annotation to
- * each field, leaving any hand-written getter or setter in place.
- */
-import { observable, makeObservable, action, computed, observe, } from 'mobx';
-import { PropertyType } from '../transaction/types/index.js';
-import { getContext } from '../context.js';
-/**
- * Makes a model instance's schema-defined properties observable with MobX. For
- * each field it reads the {@link PropertyMetadata} and applies the matching MobX
- * annotation — a plain observable for stored values, a computed for derived
- * getters, and an action for mutating methods — while leaving any field that
- * already declares its own getter and setter untouched. If the model provides
- * its own `setupObservability` or sets `_hasCustomObservability`, this function
- * defers to it and does nothing.
- */
-export function M1(target, propertyMetadata, referenceMetadata) {
-    // MobX accepts an annotations map keyed by PropertyKey. We build it
-    // from the runtime metadata, so the keys are strings — not
-    // statically derivable from `keyof T`.
-    const annotations = {};
-    // Helper to check if property has a getter
-    const hasGetter = (propName) => {
-        let obj = target;
-        while (obj) {
-            const descriptor = Object.getOwnPropertyDescriptor(obj, propName);
-            if (descriptor?.get)
-                return true;
-            obj = Object.getPrototypeOf(obj);
-            if (obj === Object.prototype)
-                break;
-        }
-        return false;
-    };
-    // Helper to check if property has a setter
-    const hasSetter = (propName) => {
-        let obj = target;
-        while (obj) {
-            const descriptor = Object.getOwnPropertyDescriptor(obj, propName);
-            if (descriptor?.set)
-                return true;
-            obj = Object.getPrototypeOf(obj);
-            if (obj === Object.prototype)
-                break;
-        }
-        return false;
-    };
-    // Skip if target has its own observability setup
-    // This allows models like Task to handle their own MobX setup
-    if (target.setupObservability || target._hasCustomObservability) {
-        getContext().modelDebugLogger?.logDebug(`${target.constructor.name} has custom observability, skipping M1`);
-        return;
-    }
-    // Process each property based on its type
-    for (const [propName, metadata] of propertyMetadata) {
-        const hasCustomGetter = hasGetter(propName);
-        const hasCustomSetter = hasSetter(propName);
-        // If property has custom getter/setter, respect it
-        if (hasCustomGetter && hasCustomSetter) {
-            // Property is fully managed, skip it
-            continue;
-        }
-        switch (metadata.type) {
-            case PropertyType.property:
-            case PropertyType.ephemeralProperty:
-                if (hasCustomGetter) {
-                    // Has getter but no setter - mark as computed
-                    annotations[propName] = computed;
-                }
-                else {
-                    // Pick the cheapest observability that still captures
-                    // reactivity at the granularity consumers subscribe to. Default
-                    // `observable` is deep, which on JSON-blob fields produces a
-                    // recursive atom tree (catastrophic on chart specs, ProseMirror
-                    // docs, style maps) — see PropertyMetadata.observability docs.
-                    switch (metadata.observability) {
-                        case 'ref':
-                            annotations[propName] = observable.ref;
-                            break;
-                        case 'shallow':
-                            annotations[propName] = observable.shallow;
-                            break;
-                        case 'deep':
-                        case undefined:
-                        default:
-                            annotations[propName] = observable;
-                            break;
-                    }
-                }
-                break;
-            case PropertyType.reference:
-                // Foreign key ID property
-                const idPropName = propName.endsWith('Id') ? propName : `${propName}Id`;
-                if (!hasGetter(idPropName) && !hasSetter(idPropName)) {
-                    annotations[idPropName] = observable;
-                }
-                break;
-            case PropertyType.referenceModel:
-                // Computed getter for referenced model
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = computed;
-                }
-                break;
-            case PropertyType.referenceCollection:
-                // Observable collection
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = observable;
-                }
-                break;
-            case PropertyType.backReference:
-                // Computed back-reference
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = computed;
-                }
-                break;
-            case PropertyType.referenceArray:
-                // Observable array of IDs
-                if (!propName.endsWith('Ids')) {
-                    const idsPropName = `${propName}Ids`;
-                    if (!hasGetter(idsPropName) && !hasSetter(idsPropName)) {
-                        annotations[idsPropName] = observable;
-                    }
-                }
-                if (!hasCustomGetter && !hasCustomSetter) {
-                    annotations[propName] = observable;
-                }
-                break;
-        }
-    }
-    // Add standard model properties only if they don't exist
-    if (!hasGetter('id') && !hasSetter('id')) {
-        annotations.id = observable;
-    }
-    if (!hasGetter('createdAt') && !hasSetter('createdAt')) {
-        annotations.createdAt = observable;
-    }
-    if (!hasGetter('updatedAt') && !hasSetter('updatedAt')) {
-        annotations.updatedAt = observable;
-    }
-    if (!hasGetter('modifiedProperties') && !hasSetter('modifiedProperties')) {
-        // Track map membership, but keep change payloads as plain values. These
-        // entries are replaced rather than mutated and later cross IndexedDB's
-        // structured-clone boundary, where MobX's deep proxies are invalid.
-        annotations.modifiedProperties = observable.shallow;
-    }
-    // Add actions only if methods exist and aren't already actions.
-    // `Reflect.get` keeps the read typed without an index-signature
-    // cast — `target` is `M1Target`, which deliberately doesn't index
-    // by arbitrary string (we don't want to sneak random fields in).
-    const actionMethods = [
-        'propertyChanged',
-        'markAsPersisted',
-        'clearChanges',
-        'consumeModifiedFields',
-        'updateFromData',
-        'applyChanges',
-    ];
-    for (const methodName of actionMethods) {
-        if (typeof Reflect.get(target, methodName) === 'function') {
-            annotations[methodName] = action;
-        }
-    }
-    // Log setup for debugging
-    const modelName = target.constructor.name;
-    const observableProps = Object.keys(annotations).filter((k) => annotations[k] === observable);
-    const computedProps = Object.keys(annotations).filter((k) => annotations[k] === computed);
-    getContext().modelDebugLogger?.logObservableSetup(modelName, observableProps, computedProps);
-    // Merge any extra annotations declared by the model (e.g., computed for query getters)
-    if (target._extraMobxAnnotations && typeof target._extraMobxAnnotations === 'object') {
-        Object.assign(annotations, target._extraMobxAnnotations);
-    }
-    // Apply MobX decorators
-    try {
-        // Only apply if we have annotations to apply
-        if (Object.keys(annotations).length > 0) {
-            makeObservable(target, annotations);
-            // Bridge MobX's observable setter to `propertyChanged()` so a direct
-            // assignment like `layer.position = newPos` still records a change for the
-            // transaction queue, and the update reaches the server. Product code
-            // assigns model properties directly in many places (drag, resize,
-            // formatting, keyboard nudge, AI tools), so those writes must sync.
-            //
-            // `observe()` attaches a post-set listener without replacing MobX's
-            // accessors, so the observable keeps its normal reactivity and we get a
-            // synchronous change event to forward to `propertyChanged()`. Only
-            // persisted fields (`PropertyType.property`) are observed, so ephemeral UI
-            // state and computed or reference fields do not leak into
-            // `modifiedProperties`.
-            //
-            // Construction-time writes (the constructor's initial field
-            // population from wire data) also fire `observe` — so we gate with
-            // `target._isNew` and a transient `_isConstructing` flag: any change
-            // that happens before the model is marked persisted is an initial
-            // hydration, not a user edit.
-            if (!target._hasCustomObservability) {
-                for (const [propName, metadata] of propertyMetadata) {
-                    if (metadata.type !== PropertyType.property)
-                        continue;
-                    // Only entries annotated as `observable` are safe to `observe()`. Do
-                    // not gate on
-                    // `Object.getOwnPropertyDescriptor(target, propName).get/set`:
-                    // `makeObservable(target, annotations)` has already installed its own
-                    // getter/setter by this point, so that descriptor check flags every
-                    // field as custom and silently skips every observer. That mistake left
-                    // `modifiedProperties` empty for dynamic models, so the transaction
-                    // queue found no changes to send and the server acked a no-op
-                    // mutation.
-                    if (!(propName in annotations))
-                        continue;
-                    // Accept any flavor of `observable` (deep, ref, shallow). `observe()`
-                    // works on all three — the listener fires on the property
-                    // reassignment, regardless of how the value is enhanced
-                    // internally. Crucially, this lets `propertyChanged()` (and the
-                    // transaction queue) still see writes to JSON-blob fields
-                    // annotated as `observable.ref`. Gating on the bare `observable`
-                    // constant alone would silently drop those writes — see the
-                    // `input: {}` regression captured in the comment above for the
-                    // same failure mode.
-                    const ann = annotations[propName];
-                    if (ann !== observable && ann !== observable.ref && ann !== observable.shallow)
-                        continue;
-                    try {
-                        // Cross the runtime/static boundary: propName is a string
-                        // from the propertyMetadata Map iteration. At runtime it's
-                        // guaranteed to be a key on `target` (we just wrote the
-                        // annotation entry for it via makeObservable above). The
-                        // cast to `keyof T` reflects that runtime invariant —
-                        // it's not "I don't know," it's "I know but TS can't see
-                        // the proof from here." MobX's IValueDidChange<T[K]>
-                        // gives the change parameter a concrete typed value.
-                        const key = propName;
-                        observe(target, key, (change) => {
-                            // Only track updates, not add/delete. For scalar observables,
-                            // MobX emits `{ type: 'update', oldValue, newValue }`.
-                            if (change.type !== 'update')
-                                return;
-                            // Skip initial hydration writes. `_isNew` stays true until
-                            // the model is `markAsPersisted()`, and the first wave of
-                            // setters runs during construction BEFORE this observer
-                            // would exist (observers are installed now, on this line);
-                            // but defensively still gate, because callers that
-                            // pre-construct models with partial data then bulk-assign
-                            // would otherwise spuriously fill `modifiedProperties`.
-                            if (target._isConstructing)
-                                return;
-                            if (typeof target.propertyChanged === 'function') {
-                                target.propertyChanged(propName, change.oldValue, change.newValue);
-                            }
-                        });
-                    }
-                    catch {
-                        // If a property isn't observable for any reason (e.g. it
-                        // was filtered out by the annotations logic but still shows
-                        // up in metadata), silently skip — propertyChanged tracking
-                        // is best-effort, not a correctness guarantee.
-                    }
-                }
-            }
-        }
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        getContext().modelDebugLogger?.logError(modelName, 'OBSERVABLE_SETUP', errorMessage, {
-            annotations: Object.keys(annotations),
-            target: Object.keys(target),
-        });
-        throw error;
-    }
-}
-/**
- * Wraps a model class so every instance is made observable at construction time
- * by calling {@link M1}. A class that manages its own observability — one whose
- * prototype declares `setupObservability` or `_hasCustomObservability` — is
- * returned unchanged. The wrapper preserves the original class name and its
- * static members.
- */
-export function makeModelObservable(modelClass, propertyMetadata, referenceMetadata) {
-    // Check if class already handles observability
-    if (modelClass.prototype.setupObservability || modelClass.prototype._hasCustomObservability) {
-        return modelClass;
-    }
-    // Create wrapper class
-    const WrappedClass = class extends modelClass {
-        constructor(...args) {
-            super(...args);
-            M1(this, propertyMetadata, referenceMetadata);
-        }
-    };
-    // Preserve class name
-    Object.defineProperty(WrappedClass, 'name', {
-        value: modelClass.name,
-        configurable: true,
-    });
-    // Copy static properties
-    Object.setPrototypeOf(WrappedClass, modelClass);
-    return WrappedClass;
-}
-/**
- * Reports whether a named property is one that {@link M1} makes observable —
- * that is, a stored value, an ephemeral value, a reference collection, or a
- * reference array. Returns `false` for an unknown property and for a computed
- * reference.
- */
-export function isObservableProperty(target, propName, propertyMetadata) {
-    const metadata = propertyMetadata.get(propName);
-    if (!metadata)
-        return false;
-    return [
-        PropertyType.property,
-        PropertyType.ephemeralProperty,
-        PropertyType.referenceCollection,
-        PropertyType.referenceArray,
-    ].includes(metadata.type);
-}
-/**
- * Returns the names of the properties that {@link M1} treats as computed: the
- * referenced-model and back-reference fields derived from a foreign key.
- */
-export function getComputedProperties(propertyMetadata) {
-    const computed = [];
-    for (const [propName, metadata] of propertyMetadata) {
-        if (metadata.type === PropertyType.referenceModel ||
-            metadata.type === PropertyType.backReference) {
-            computed.push(propName);
-        }
-    }
-    return computed;
-}

package/dist/views/QueryView.d.ts

@@ -1,79 +0,0 @@
-/**
- * QueryView<T> — Incrementally maintained materialized view for a single query.
- *
- * Instead of scanning the full collection on every render, a QueryView
- * builds the result set once, then maintains it via handleAdded /
- * handleUpdated / handleRemoved calls from the ViewRegistry.
- *
- * `results` is a stable MobX observable array — components observe it
- * directly and receive granular updates (splice/push, never replacement).
- */
-import { type IObservableArray } from 'mobx';
-import { type Model } from '../Model.js';
-import { ModelScope } from '../transaction/types/index.js';
-import type { ViewRegistry } from './ViewRegistry.js';
-import type { IncrementalView } from './incrementalView.js';
-/**
- * The slice of the object pool that a {@link QueryView} reads. It is a minimal
- * structural interface rather than the concrete pool class, which lets a query
- * view avoid importing the pool and so breaks what would otherwise be an import
- * cycle — the pool imports {@link QueryView} to construct one. The concrete
- * pool satisfies this interface structurally.
- */
-export interface QueryViewPool {
-    hasForeignKeyIndex(typename: string, fieldName: string): boolean;
-    getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
-    getByTypeName(modelName: string, scope?: ModelScope): Model[];
-}
-export interface QueryViewOptions<T> {
-    where?: Partial<T>;
-    filter?: (entity: T) => boolean;
-    orderBy?: keyof T & string;
-    order?: 'asc' | 'desc';
-    limit?: number;
-    offset?: number;
-    /** Lifecycle filter — `live` (the default), `archived`, or `all`. It is
-     *  named `state` rather than `scope` so it does not collide with the
-     *  sync-group `scope`. */
-    state?: ModelScope;
-}
-export declare class QueryView<T extends Record<string, unknown>> implements IncrementalView {
-    /** The full (unlimited) internal result set, kept sorted. */
-    private _internal;
-    /**
-     * Public observable result set — windowed by offset/limit.
-     * Components observe this directly.
-     */
-    readonly results: IObservableArray<T>;
-    private readonly typename;
-    private readonly pool;
-    private readonly registry;
-    private readonly whereEntries;
-    private readonly filterFn;
-    private readonly sortKey;
-    private readonly sortDir;
-    private readonly limitN;
-    private readonly offsetN;
-    private readonly scope;
-    /** FK-index optimization: if the where clause targets a single FK-indexed field. */
-    private readonly fkField;
-    private readonly fkValue;
-    private disposed;
-    constructor(typename: string, pool: QueryViewPool, registry: ViewRegistry, options?: QueryViewOptions<T>);
-    private initialScan;
-    handleAdded(model: Record<string, unknown>): void;
-    handleUpdated(model: Record<string, unknown>): void;
-    handleRemoved(modelId: string): void;
-    dispose(): void;
-    /** Check whether an entity passes both `where` and `filter`. */
-    private matchesFilter;
-    /** Insert entity into _internal at the correct sorted position. */
-    private insertSorted;
-    /** Find index of entity by id in _internal. */
-    private findIndexById;
-    /**
-     * Synchronize the public `results` array with the windowed slice of
-     * `_internal`. Mutates in place to keep the reference stable.
-     */
-    private syncWindow;
-}

package/dist/views/QueryView.js

@@ -1,218 +0,0 @@
-/**
- * QueryView<T> — Incrementally maintained materialized view for a single query.
- *
- * Instead of scanning the full collection on every render, a QueryView
- * builds the result set once, then maintains it via handleAdded /
- * handleUpdated / handleRemoved calls from the ViewRegistry.
- *
- * `results` is a stable MobX observable array — components observe it
- * directly and receive granular updates (splice/push, never replacement).
- */
-import { observable, runInAction } from 'mobx';
-import { modelAsRow } from '../Model.js';
-import { ModelScope } from '../transaction/types/index.js';
-import { compareValues, binaryInsertionIndex, findIndexById, } from './incrementalView.js';
-// ---------------------------------------------------------------------------
-// QueryView
-// ---------------------------------------------------------------------------
-export class QueryView {
-    /** The full (unlimited) internal result set, kept sorted. */
-    _internal;
-    /**
-     * Public observable result set — windowed by offset/limit.
-     * Components observe this directly.
-     */
-    results;
-    typename;
-    pool;
-    registry;
-    whereEntries;
-    filterFn;
-    sortKey;
-    sortDir;
-    limitN;
-    offsetN;
-    scope;
-    /** FK-index optimization: if the where clause targets a single FK-indexed field. */
-    fkField;
-    fkValue;
-    disposed = false;
-    constructor(typename, pool, registry, options = {}) {
-        this.typename = typename;
-        this.pool = pool;
-        this.registry = registry;
-        // Parse options
-        this.whereEntries = options.where
-            ? Object.entries(options.where).filter(([, v]) => v !== undefined)
-            : null;
-        this.filterFn = options.filter ?? null;
-        this.sortKey = options.orderBy ?? null;
-        this.sortDir = options.order === 'desc' ? -1 : 1;
-        this.limitN = options.limit;
-        this.offsetN = options.offset ?? 0;
-        this.scope = options.state ?? ModelScope.live;
-        // Check for FK-index optimization: single-field where with an indexed FK
-        this.fkField = null;
-        this.fkValue = null;
-        const soleWhereEntry = this.whereEntries && this.whereEntries.length === 1 ? this.whereEntries[0] : undefined;
-        if (soleWhereEntry && typeof soleWhereEntry[1] === 'string') {
-            const [field, value] = soleWhereEntry;
-            if (pool.hasForeignKeyIndex(typename, field)) {
-                this.fkField = field;
-                this.fkValue = value;
-            }
-        }
-        // Create observable arrays (shallow — models are already observable)
-        this._internal = observable.array([], { deep: false });
-        this.results = observable.array([], { deep: false });
-        // Perform initial scan
-        this.initialScan();
-        // Register for incremental updates
-        this.registry.register(typename, this);
-    }
-    // -----------------------------------------------------------------------
-    // Initial scan
-    // -----------------------------------------------------------------------
-    initialScan() {
-        let candidates;
-        if (this.fkField && this.fkValue) {
-            // O(1) FK-index lookup
-            candidates = this.pool.getByForeignKey(this.typename, this.fkField, this.fkValue);
-        }
-        else {
-            candidates = this.pool.getByTypeName(this.typename, this.scope);
-        }
-        const matching = [];
-        for (const model of candidates) {
-            const entity = modelAsRow(model);
-            if (this.matchesFilter(entity)) {
-                matching.push(entity);
-            }
-        }
-        // Sort
-        if (this.sortKey) {
-            const key = this.sortKey;
-            const dir = this.sortDir;
-            matching.sort((a, b) => compareValues(a[key], b[key], dir));
-        }
-        runInAction(() => {
-            this._internal.replace(matching);
-            this.syncWindow();
-        });
-    }
-    // -----------------------------------------------------------------------
-    // Incremental update handlers (called by ViewRegistry)
-    // -----------------------------------------------------------------------
-    handleAdded(model) {
-        if (this.disposed)
-            return;
-        const entity = model;
-        const passesFilter = this.matchesFilter(entity);
-        if (!passesFilter)
-            return;
-        runInAction(() => {
-            this.insertSorted(entity);
-            this.syncWindow();
-        });
-    }
-    handleUpdated(model) {
-        if (this.disposed)
-            return;
-        const entity = model;
-        const id = entity.id;
-        const idx = id !== undefined ? this.findIndexById(id) : -1;
-        const matchesNow = this.matchesFilter(entity);
-        runInAction(() => {
-            if (idx >= 0 && matchesNow) {
-                // Was in view and still matches.
-                // Models are plain objects (not MobX-observable), so we must notify
-                // observers that the data changed. Splice-in-place triggers the
-                // observable array to fire, which causes useQuery consumers to
-                // re-render with fresh property values.
-                this._internal.splice(idx, 1);
-                this.insertSorted(entity);
-            }
-            else if (idx >= 0 && !matchesNow) {
-                // Was in view but no longer matches — remove
-                this._internal.splice(idx, 1);
-            }
-            else if (idx < 0 && matchesNow) {
-                // Wasn't in view but now matches — add
-                this.insertSorted(entity);
-            }
-            this.syncWindow();
-        });
-    }
-    handleRemoved(modelId) {
-        if (this.disposed)
-            return;
-        const idx = this.findIndexById(modelId);
-        if (idx < 0)
-            return;
-        runInAction(() => {
-            this._internal.splice(idx, 1);
-            this.syncWindow();
-        });
-    }
-    // -----------------------------------------------------------------------
-    // Dispose
-    // -----------------------------------------------------------------------
-    dispose() {
-        if (this.disposed)
-            return;
-        this.disposed = true;
-        this.registry.unregister(this.typename, this);
-    }
-    // -----------------------------------------------------------------------
-    // Private helpers
-    // -----------------------------------------------------------------------
-    /** Check whether an entity passes both `where` and `filter`. */
-    matchesFilter(entity) {
-        // Note: scope is tracked per-entry in the InstanceCache, not on the model.
-        // The initial scan handles scope via getByTypeName(typename, scope).
-        // Incremental notifications from the pool are scope-appropriate since
-        // add/upsert/remove reflect the pool's authoritative scope tracking.
-        // Where clause: declarative field matching
-        if (this.whereEntries) {
-            for (const [key, value] of this.whereEntries) {
-                if (entity[key] !== value)
-                    return false;
-            }
-        }
-        // Arbitrary predicate
-        if (this.filterFn) {
-            if (!this.filterFn(entity))
-                return false;
-        }
-        return true;
-    }
-    /** Insert entity into _internal at the correct sorted position. */
-    insertSorted(entity) {
-        if (this.sortKey) {
-            const idx = binaryInsertionIndex(this._internal, entity, this.sortKey, this.sortDir);
-            this._internal.splice(idx, 0, entity);
-        }
-        else {
-            this._internal.push(entity);
-        }
-    }
-    /** Find index of entity by id in _internal. */
-    findIndexById(id) {
-        return findIndexById(this._internal, id);
-    }
-    /**
-     * Synchronize the public `results` array with the windowed slice of
-     * `_internal`. Mutates in place to keep the reference stable.
-     */
-    syncWindow() {
-        const start = this.offsetN;
-        const end = this.limitN !== undefined ? start + this.limitN : this._internal.length;
-        const windowed = this._internal.slice(start, end);
-        // Minimal diff: only splice if contents differ
-        if (windowed.length === this.results.length &&
-            windowed.every((item, i) => this.results[i] === item)) {
-            return; // no change
-        }
-        this.results.replace(windowed);
-    }
-}

package/dist/views/ViewRegistry.d.ts

@@ -1,20 +0,0 @@
-/**
- * ViewRegistry — tracks active QueryViews per typename.
- *
- * When the InstanceCache mutates a model, it calls notifyAdded / notifyUpdated /
- * notifyRemoved on the registry, which fans the event out to every active
- * QueryView subscribed to that typename.
- */
-import { type Model } from '../Model.js';
-import type { IncrementalView } from './incrementalView.js';
-export declare class ViewRegistry {
-    private views;
-    register(typename: string, view: IncrementalView): void;
-    unregister(typename: string, view: IncrementalView): void;
-    /** Called by InstanceCache after a model is added to the pool. */
-    notifyAdded(typename: string, model: Model): void;
-    /** Called by InstanceCache after a model is updated in the pool. */
-    notifyUpdated(typename: string, model: Model): void;
-    /** Called by InstanceCache after a model is removed from the pool. */
-    notifyRemoved(typename: string, modelId: string): void;
-}