@abloatai/humans 0.37.0

package/dist/local/utils/mobxSetup.js

@@ -0,0 +1,330 @@
+/**
+ * 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 '@abloatai/transaction/types';
+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/local/views/QueryView.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 '@abloatai/transaction/types';
+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/local/views/QueryView.js

@@ -0,0 +1,218 @@
+/**
+ * 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 '@abloatai/transaction/types';
+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/local/views/ViewRegistry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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;
+}