@abloatai/humans 0.37.0

package/dist/local/query/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Structured query types for the `/sync/query` endpoint.
+ *
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['blocks']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every block whose `sectionId` falls in a set of
+ * ids.
+ */
+export type { WherePrimitive, WhereOp, WhereClause, LoadWhere, } from '@abloatai/transaction/resources/where';
+import type { WhereClause } from '@abloatai/transaction/resources/where';
+/** A single structured fetch request. */
+export interface Query {
+    /**
+     * Client-facing model name (e.g. "File", "Block", "Message").
+     * The server's adapter maps this to the actual database table.
+     */
+    model: string;
+    /**
+     * The conditions to filter by, combined with AND. Empty or omitted returns
+     * every row the caller may see; reads are still scoped to the caller's
+     * organization on the server. Use `['col', 'IN', values]` to batch a read by
+     * any column.
+     */
+    where?: readonly WhereClause[];
+    /**
+     * The relations to fetch with each row, named as they are declared on this
+     * model in the schema. The server resolves each name from the schema's
+     * relation metadata and joins the related rows in. They come back nested
+     * under the relation key:
+     *
+     *   { __typename: 'Section', id: '…', blocks: [{ __typename: 'Block', … }] }
+     */
+    related?: readonly string[];
+    /**
+     * Row limit. Applied after where + JOIN, before related nesting.
+     * Omit for no limit.
+     */
+    limit?: number;
+    /**
+     * Column to order by. For stable pagination. Omit for unordered.
+     */
+    orderBy?: string;
+    /** Order direction. Defaults to `'asc'`. */
+    order?: 'asc' | 'desc';
+}
+/** Request body for POST /sync/query. */
+export interface QueryBatch {
+    /**
+     * Batch of queries to execute in one round trip. Results are
+     * returned in request order at the same indices. Keep batches
+     * small — the server caps at 16 queries per batch by default.
+     */
+    queries: Query[];
+}
+/** Response body from POST /sync/query. */
+export interface QueryBatchResult {
+    /**
+     * The result of each query, in request order: `results[i]` corresponds to
+     * `queries[i]`. Each element is an array of rows, or an object bundling
+     * several named row collections when the source returns more than one. Every
+     * row carries a `__typename` field naming its model, so callers can dispatch
+     * on it, along with any requested `related` rows nested under their relation
+     * key.
+     *
+     * A query that fails on the server comes back as an empty array, which is
+     * indistinguishable from a query that simply matched nothing — treat an empty
+     * result as "no rows", not as proof the query succeeded. The element type is
+     * `unknown` because one batch can mix row shapes, so narrow each result
+     * before use.
+     */
+    results: unknown[];
+    /**
+     * The server watermark observed after the batch ran. Model reads expose this
+     * as `stamp`, and callers thread it into `commits.create({ readAt })` so the
+     * server can reject a write built on stale data.
+     */
+    lastSyncId?: number;
+}

package/dist/local/query/types.js

@@ -0,0 +1,16 @@
+/**
+ * Structured query types for the `/sync/query` endpoint.
+ *
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['blocks']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every block whose `sectionId` falls in a set of
+ * ids.
+ */
+export {};

package/dist/local/schema/serialize.d.ts

@@ -0,0 +1 @@
+export * from '@abloatai/transaction/schema/serialize';

package/dist/local/schema/serialize.js

@@ -0,0 +1 @@
+export * from '@abloatai/transaction/schema/serialize';

package/dist/local/store/queryApi.d.ts

@@ -0,0 +1,13 @@
+import { ModelScope, type InstanceCache } from '../InstanceCache.js';
+import type { Model } from '../Model.js';
+import type { ModelConstructor, QueryResult } from '../BaseSyncedStore.js';
+export interface QueryOptions {
+    predicate?: (model: Model) => boolean;
+    state?: ModelScope;
+    orderBy?: keyof Model;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+export declare function queryByClass(objectPool: InstanceCache, pendingDeletes: ReadonlySet<string>, modelClass: ModelConstructor<Model>, options?: QueryOptions): QueryResult<Model>;
+export declare function countModels(objectPool: InstanceCache, modelClass: ModelConstructor<Model>, pendingDeletes: ReadonlySet<string>, predicate?: (model: Model) => boolean): number;

package/dist/local/store/queryApi.js

@@ -0,0 +1,35 @@
+import { ModelScope } from '../InstanceCache.js';
+export function queryByClass(objectPool, pendingDeletes, modelClass, options) {
+    const modelName = objectPool.registry.getModelNameFromConstructor(modelClass);
+    if (!modelName)
+        return { data: [], total: 0, hasMore: false };
+    let models = objectPool
+        .getByType(modelClass, options?.state ?? ModelScope.live)
+        .filter((model) => !pendingDeletes.has(model.id));
+    if (options?.predicate)
+        models = models.filter(options.predicate);
+    const total = models.length;
+    if (options?.orderBy) {
+        const field = options.orderBy;
+        const direction = options.order === 'desc' ? -1 : 1;
+        models.sort((a, b) => {
+            const av = a.getField(field);
+            const bv = b.getField(field);
+            if (av == null || bv == null)
+                return 0;
+            return av < bv ? -direction : av > bv ? direction : 0;
+        });
+    }
+    if (options?.offset)
+        models = models.slice(options.offset);
+    const hasMore = options?.limit ? models.length > options.limit : false;
+    if (options?.limit)
+        models = models.slice(0, options.limit);
+    return { data: models, total, hasMore };
+}
+export function countModels(objectPool, modelClass, pendingDeletes, predicate) {
+    const models = objectPool
+        .getByType(modelClass, ModelScope.live)
+        .filter((model) => !pendingDeletes.has(model.id));
+    return predicate ? models.filter(predicate).length : models.length;
+}

package/dist/local/storeContract.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The framework-neutral store contract. {@link SyncStoreContract} is the minimal
+ * store interface the SDK's hooks and mutators are written against, and
+ * {@link BaseSyncedStore} is the concrete class that implements it. Framework
+ * integrations, such as the React bindings, re-export these types, so a hook can
+ * accept any store that satisfies the contract without depending on a particular
+ * UI framework.
+ *
+ * This module is type-only: it has no runtime imports and contributes nothing to
+ * the runtime bundle beyond the erased interface declarations.
+ */
+import type { Model } from './Model.js';
+import type { ModelScope } from '@abloatai/transaction/types';
+import type { QueryView, QueryViewOptions } from './views/QueryView.js';
+import type { ViewRegistry } from './views/ViewRegistry.js';
+import type { ParticipantScope } from './sync/participants.js';
+/**
+ * A snapshot of the client's synchronization state, shaped for binding to UI.
+ * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
+ * the `useSyncStatus()` hook reads its fields to render connection and progress
+ * indicators.
+ */
+export interface SyncStatus {
+    state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
+    progress: number;
+    error?: Error;
+    /** When true, the error is a session/auth error requiring re-authentication. */
+    isSessionError: boolean;
+    lastSyncAt?: Date;
+    pendingChanges: number;
+    offlineSince?: Date;
+}
+/**
+ * A single locally-originated mutation, observed as it flows through the commit
+ * stream. The undo system records these to build its inverse operations: one is
+ * emitted per local create, update, delete, or archive. Changes arriving from
+ * other participants do not appear here — they apply through a separate path
+ * that does not queue mutations. Because `previousData` captures the field
+ * values as they were before the edit, each event carries everything needed to
+ * derive its inverse, with no separate snapshot step. A store exposes this
+ * stream through {@link SyncStoreContract.subscribeLocalMutations}.
+ */
+export interface LocalMutation {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    /** The registered name of the mutated model, for example `'Block'`. */
+    modelName: string;
+    modelId: string;
+    /** The new field values, for a create or an update. */
+    data?: Record<string, unknown> | null;
+    /** The field values as they were before the edit. For an update these form
+     *  the inverse patch; for a delete they hold the full row needed to recreate
+     *  it. */
+    previousData?: Record<string, unknown> | null;
+}
+/**
+ * The minimal store interface the SDK's hooks and mutators depend on. Provide a
+ * concrete store that implements it — {@link BaseSyncedStore} is the built-in
+ * implementation — and the hooks work against your store without knowing its
+ * exact type. Optional members exist so lightweight test doubles can implement
+ * only the parts they exercise.
+ */
+export interface SyncStoreContract {
+    /**
+     * Subscribes to the stream of local mutations for undo recording, delivering
+     * each optimistic write before it is acknowledged by the server. See
+     * {@link LocalMutation}. Returns a function that removes the subscription.
+     * This is optional: when a store does not implement it, undo scopes simply
+     * record nothing.
+     */
+    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
+    retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
+    queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
+        predicate?: (model: Model) => boolean;
+        scope?: ModelScope;
+        orderBy?: keyof Model;
+        order?: 'asc' | 'desc';
+        limit?: number;
+        offset?: number;
+    }): {
+        data: Model[];
+    };
+    /**
+     * Saves one entity, creating it if new or updating it if it already exists.
+     * Calling `save` repeatedly within the same tick is efficient: the writes are
+     * coalesced and persisted, then sent to the server, as a single commit. There
+     * is deliberately no bulk method — issue one `save` per row and let the tick
+     * boundary batch them.
+     *
+     * Pass `skipValidation` on trusted, high-volume paths — bulk import or
+     * hydration, where the data has already been validated — to skip the per-row
+     * schema check, which is a measurable cost at that volume.
+     */
+    save(model: Model, options?: {
+        skipValidation?: boolean;
+    }): Promise<void>;
+    delete(model: Model): Promise<void>;
+    archive(model: Model): Promise<void>;
+    unarchive(model: Model): Promise<void>;
+    /** The in-memory object pool: look up individual entities or collections by
+     *  id or model name, create views, and resolve foreign-key relationships. */
+    pool: {
+        get(id: string): Model | undefined;
+        getByTypeName(typename: string, scope?: ModelScope): Model[];
+        getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
+        createFromData(data: Record<string, unknown>): Model | null;
+        hasForeignKeyIndex(typename: string, fieldName: string): boolean;
+        createView<T extends Record<string, unknown>>(typename: string, options?: QueryViewOptions<T>): QueryView<T>;
+        viewRegistry: ViewRegistry;
+    };
+    /**
+     * Reactive getters for the current sync state. In the built-in store these
+     * are backed by observable computeds, so reading them inside a reactive
+     * context — an observer component or a reaction — re-runs that context when
+     * the state changes. Code that prefers not to work with the reactivity system
+     * directly can read the same values through the `useSyncStatus()` hook.
+     */
+    readonly isReady: boolean;
+    readonly isSyncing: boolean;
+    readonly isOffline: boolean;
+    readonly isReconnecting: boolean;
+    readonly isError: boolean;
+    readonly hasUnsyncedChanges: boolean;
+    /**
+     * Manages the connection's area of interest — the dynamic set of data it
+     * subscribes to. Call `enterScope` and `leaveScope` to move that interest as
+     * the user navigates between documents, and `pinScope` and `unpinScope` to
+     * keep a scope subscribed while it stays important, such as while a claim is
+     * held. Every scope resolves through the same resolver the claim path uses, so
+     * read subscriptions and write claims always agree on which group they refer
+     * to. These are optional and do nothing until the connection is open.
+     */
+    enterScope?(scope: ParticipantScope, opts?: {
+        hydrate?: boolean;
+    }): Promise<void>;
+    leaveScope?(scope: ParticipantScope): Promise<void>;
+    pinScope?(scope: ParticipantScope): Promise<void>;
+    unpinScope?(scope: ParticipantScope): Promise<void>;
+    /**
+     * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
+     * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,
+     * and `error` — to present the current sync state. It is part of the contract
+     * so hooks and test doubles can read or set it directly.
+     */
+    readonly syncStatus: SyncStatus;
+}

package/dist/local/storeContract.js

@@ -0,0 +1,12 @@
+/**
+ * The framework-neutral store contract. {@link SyncStoreContract} is the minimal
+ * store interface the SDK's hooks and mutators are written against, and
+ * {@link BaseSyncedStore} is the concrete class that implements it. Framework
+ * integrations, such as the React bindings, re-export these types, so a hook can
+ * accept any store that satisfies the contract without depending on a particular
+ * UI framework.
+ *
+ * This module is type-only: it has no runtime imports and contributes nothing to
+ * the runtime bundle beyond the erased interface declarations.
+ */
+export {};

package/dist/local/stores/DatabaseManager.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Manages the client-side IndexedDB databases the sync engine keeps in the
+ * browser. There are two tiers. A single registry database, `ablo_databases`,
+ * records metadata about every workspace database. Each user-and-workspace pair
+ * then gets its own data database, named `ablo_<hash>`, that holds the synced
+ * rows. {@link DatabaseManager} creates, versions, and deletes both tiers.
+ */
+import type { RuntimeContext } from '../RuntimeContext.js';
+import { type PersistenceIdentity } from './persistenceIdentity.js';
+export type { PersistenceIdentity } from './persistenceIdentity.js';
+export interface DatabaseInfo {
+    name: string;
+    namespaceVersion: number;
+    userId: string;
+    workspaceId: string;
+    participantKind: string;
+    projectId: string | null;
+    environment: 'sandbox' | 'production' | null;
+    sandboxId: string | null;
+    schemaHash: string;
+    schemaVersion: number;
+    userVersion?: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface WorkspaceMetadata {
+    lastSyncId: number;
+    firstSyncId: number;
+    backendDatabaseVersion: number;
+    subscribedSyncGroups: string[];
+    updatedAt: Date;
+    schemaHash?: string;
+    syncGroups?: string[];
+}
+/**
+ * DatabaseManager - Manages Ablo's two-tier database architecture
+ *
+ * Key responsibilities:
+ * - Manages ablo_databases (database registry)
+ * - Creates workspace-specific databases (ablo_hash)
+ * - Handles database migration and versioning
+ * - Provides database info and metadata management
+ */
+export declare class DatabaseManager {
+    private readonly runtime;
+    private metaDb;
+    private readonly metaDbName;
+    constructor(runtime?: RuntimeContext);
+    /**
+     * Initialize the meta database (ablo_databases)
+     */
+    initializeMetaDatabase(): Promise<void>;
+    /**
+     * Calculate database info for a user/workspace combination
+     */
+    calculateDatabaseInfo(identity: PersistenceIdentity, userVersion?: number): Promise<DatabaseInfo>;
+    /**
+     * Register database info in ablo_databases
+     */
+    registerDatabase(info: DatabaseInfo): Promise<void>;
+    /**
+     * Get database info by name
+     */
+    getDatabaseInfo(name: string): Promise<DatabaseInfo | null>;
+    /** Remove only the named ownership records; the shared registry stays live. */
+    unregisterDatabases(names: readonly string[]): Promise<void>;
+    /**
+     * Get all databases for a user
+     */
+    getDatabasesForUser(userId: string): Promise<DatabaseInfo[]>;
+    /**
+     * Open workspace-specific database
+     */
+    openWorkspaceDatabase(dbInfo: DatabaseInfo, createStoresFn?: (db: IDBDatabase, tx: IDBTransaction) => Promise<void>): Promise<IDBDatabase>;
+    /**
+     * Read workspace metadata from __meta table
+     */
+    getWorkspaceMetadata(db: IDBDatabase): Promise<WorkspaceMetadata | null>;
+    /**
+     * Write workspace metadata to __meta table
+     */
+    setWorkspaceMetadata(db: IDBDatabase, metadata: WorkspaceMetadata): Promise<void>;
+    /**
+     * Check if a model is persisted (all instances loaded)
+     */
+    isModelPersisted(db: IDBDatabase, modelName: string): Promise<boolean>;
+    /**
+     * Mark a model as persisted
+     */
+    setModelPersisted(db: IDBDatabase, modelName: string, persisted: boolean): Promise<void>;
+    /**
+     * Get all model persistence states
+     */
+    getAllModelPersistenceStates(db: IDBDatabase): Promise<Record<string, boolean>>;
+    /**
+     * Delete a workspace database
+     */
+    deleteWorkspaceDatabase(dbInfo: DatabaseInfo): Promise<boolean>;
+    /**
+     * Get comprehensive database statistics
+     */
+    getDatabaseStatistics(): Promise<{
+        metaDatabaseSize: number;
+        totalWorkspaceDatabases: number;
+        databasesByUser: Record<string, number>;
+        schemaVersions: Record<string, number>;
+    }>;
+    /**
+     * Close all database connections
+     */
+    close(): Promise<void>;
+}