@abloatai/transaction 0.37.0

package/src/types/assertExact.ts

@@ -0,0 +1,17 @@
+/**
+ * A compile-time proof that two types are the same type, in both directions.
+ *
+ * This is how a derived shape is pinned to the shape it derives from. A plain
+ * `extends` check only proves one side is assignable to the other, which a
+ * schema that has grown a field still satisfies; both directions catch the
+ * addition. Instantiating it at a value binding turns the mismatch into a
+ * compile error at the definition site rather than at some distant caller.
+ *
+ * ```ts
+ * const _contract: AssertExact<z.infer<typeof participantRefSchema>, ParticipantRef> = true;
+ * ```
+ *
+ * The tuple wrappers stop a union operand from distributing, so a union is
+ * compared whole rather than member by member.
+ */
+export type AssertExact<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;

package/src/types/global.ts

@@ -0,0 +1,123 @@
+/**
+ * The single place where you tell the SDK about your application's types.
+ *
+ * You register your Schema, UserMeta and ClaimMeta once by augmenting the
+ * {@link Register} interface. From then on the typed SDK surface reads its
+ * types from that registration, so you never pass a generic or a `schema`
+ * argument at a call site.
+ *
+ * Registration uses TypeScript module augmentation: any file in your project
+ * can add an `interface Register` to a `declare module '@abloatai/ablo'`
+ * block, and every resolver below picks it up. Because the name is scoped to
+ * this module, the interface is simply `Register` — not a global and not
+ * prefixed.
+ *
+ * The `npx ablo init` command scaffolds this file as `ablo/register.ts`, next
+ * to `ablo/schema.ts`. Write it as a normal `.ts` module, not a hand-authored
+ * `.d.ts`: the top-level `import type { schema }` is what makes the
+ * `declare module` block merge into this interface rather than collide with it.
+ * Any `.ts` file covered by your `tsconfig` works, and it never needs to be
+ * imported anywhere.
+ *
+ * ```ts
+ * // ablo/register.ts
+ * import type { schema } from './schema';
+ *
+ * declare module '@abloatai/ablo' {
+ *   interface Register {
+ *     Schema: typeof schema;
+ *     UserMeta: { id: string; email: string };
+ *     ClaimMeta: { blocks: string[] };
+ *   }
+ * }
+ * export {};
+ * ```
+ *
+ * When `Register` is never augmented, every resolver falls back to
+ * {@link DefaultSyncShape} — a loose shape that keeps your code compiling
+ * without typed results until you opt in.
+ */
+
+import type { SchemaRecord } from '../schema/schema.js';
+
+/**
+ * The fallback shapes the resolvers use when {@link Register} has not been
+ * augmented. `DefaultSyncShape.Schema` is deliberately structural — it carries
+ * `{ models: SchemaRecord }` so hooks can still check a model-key argument
+ * against something (and satisfy the `SchemaRecord` bound), just without a
+ * typed entity shape behind it.
+ */
+export interface DefaultSyncShape {
+  // `models` is a `SchemaRecord` (not `Record<string, unknown>`) so that
+  // `ResolveSchema['models']` still satisfies the `R extends SchemaRecord`
+  // bound on the SDK hooks when no `Register` is present — e.g. a shared
+  // package (`@ablo/documents`, `@ablo/teams`) typechecked standalone, with no
+  // app registration in scope. Without this the fallback wouldn't type-check
+  // against `useAblo<R>()`/`AbloProvider<R>` and every such package would need
+  // its own ambient registration.
+  readonly Schema: { readonly models: SchemaRecord };
+  readonly UserMeta: { readonly id: string };
+  // The shape a claim's `meta` has when nothing is registered: exactly as loose
+  // as it has always been, so an unregistered program reads
+  // `claim.state({ id })?.target.meta` the way it does today. The answer to
+  // "what if nothing is declared" is the shape callers already have — never
+  // `never`, which would make every existing read an error, and never `any`,
+  // which would make every existing read a lie.
+  readonly ClaimMeta: Record<string, unknown>;
+}
+
+/**
+ * The registration interface you augment to declare your application's types.
+ * Add keys inside a `declare module '@abloatai/ablo'` block — for example
+ * `interface Register { Schema: ...; UserMeta: ...; ClaimMeta: ...; }`. It is
+ * empty by default,
+ * so any key you omit falls back to {@link DefaultSyncShape}. It is exported
+ * from the package root so your augmentation merges into this declaration.
+ *
+ * The `Schema` key holds the type returned by `defineSchema`, and
+ * {@link ResolveSchema} reads it back out.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Register {}
+
+/**
+ * Your registered schema, or the default shape when none is registered. Hooks
+ * read this to type their model-key argument and to infer the entity type they
+ * return.
+ */
+export type ResolveSchema = Register extends { Schema: infer S }
+  ? S extends { models: Record<string, unknown> }
+    ? S
+    : DefaultSyncShape['Schema']
+  : DefaultSyncShape['Schema'];
+
+/**
+ * Your registered user-metadata shape, or the default when none is registered.
+ * It carries identity information you trust from your own auth layer; the SDK
+ * does not validate it.
+ */
+export type ResolveUserMeta = Register extends { UserMeta: infer U }
+  ? U
+  : DefaultSyncShape['UserMeta'];
+
+/**
+ * The application metadata your claims carry, or the default when none is
+ * registered. It rides along on a claim's target — the SDK transports it
+ * verbatim, never interprets it, and never validates it, so the shape is
+ * yours to declare and yours alone to keep true.
+ *
+ * Declaring it here is what makes `claim.state({ id })?.target.meta` readable
+ * without a `typeof` guard, on every claim surface at once.
+ */
+export type ResolveClaimMeta = Register extends { ClaimMeta: infer M }
+  ? M
+  : DefaultSyncShape['ClaimMeta'];
+
+/**
+ * The union of your schema's model names. `useQuery(modelKey)` narrows its
+ * first argument to this union, so a misspelled or unknown model name fails at
+ * compile time.
+ */
+export type ResolveModelKey = ResolveSchema extends { models: infer M }
+  ? keyof M & string
+  : string;

package/src/types/index.ts

@@ -0,0 +1,270 @@
+/**
+ * Core type definitions for the model-driven sync layer.
+ *
+ * These types describe how a model's properties are declared, when their data
+ * is loaded, and how changes are represented on the wire as they synchronize.
+ */
+
+import type { FieldMeta } from '../schema/field.js';
+// Bound locally as well as re-exported below: a bare `export … from` forwards
+// the name to consumers without binding it in this module, so the annotations
+// further down would not resolve.
+import { LoadStrategy } from '../schema/loadStrategy.js';
+
+/**
+ * A lifecycle filter for queries: whether to return live entities, archived
+ * ones, or both.
+ */
+export enum ModelScope {
+  live = 'live',
+  archived = 'archived',
+  all = 'all',
+}
+
+/**
+ * The kinds of property a model can declare. Each kind determines how the
+ * property behaves in the sync system — whether it is persisted, how it relates
+ * to other models, and how it is loaded.
+ */
+export enum PropertyType {
+  /** A standard observable field owned by the model, both persisted and synced. */
+  property = 'property',
+
+  /** A runtime-only field that is neither persisted nor synced. */
+  ephemeralProperty = 'ephemeralProperty',
+
+  /** A foreign-key reference that stores only the related model's id. */
+  reference = 'reference',
+
+  /** A single related model resolved on demand from its id, exposed as a getter and setter. */
+  referenceModel = 'referenceModel',
+
+  /** A collection of related models — the many side of a one-to-many relationship. */
+  referenceCollection = 'referenceCollection',
+
+  /** A computed field that follows a relationship in the inverse direction. */
+  backReference = 'backReference',
+
+  /** An array of foreign-key ids — a many-to-many relationship. */
+  referenceArray = 'referenceArray',
+}
+
+// When and how a model's data is loaded from the server. Defined in
+// `../schema/loadStrategy.ts`, which the authoring surface reads from too.
+export { LoadStrategy };
+
+/**
+ * The resolved configuration for a single model property.
+ */
+export interface PropertyMetadata {
+  type: PropertyType;
+  indexed?: boolean;
+  optional?: boolean;
+  nullable?: boolean;
+  defaultValue?: unknown;
+  loadStrategy?: LoadStrategy;
+  /**
+   * How deeply the reactivity layer wraps this property's value when the model
+   * is registered. The engine uses MobX, so the choice maps directly to MobX's
+   * observability modes.
+   *
+   * - `'deep'` (the default): full recursive observability, where every nested
+   *   object or array becomes its own reactive node. Correct for scalar fields
+   *   and small structured values whose inner properties are read directly.
+   * - `'shallow'`: track the reference and array, map, and set operations, but
+   *   do not recurse into element internals. Right for collections whose
+   *   elements are replaced wholesale.
+   * - `'ref'`: track only reassignment of the value. Right for opaque JSON
+   *   blobs — chart specs, rich-text documents, style maps — that are treated
+   *   as immutable values and always read whole before being handed to a
+   *   renderer. Deep-wrapping these produces many needless reactions for no
+   *   benefit.
+   *
+   * Schema-driven registration sets this to `'ref'` automatically for fields
+   * whose wire type is `'json'`, the right default for the blob pattern.
+   */
+  observability?: 'deep' | 'shallow' | 'ref';
+}
+
+/** The constructor type of a model class, used by reference metadata to point at the related model. */
+type ModelConstructor = abstract new (...args: never[]) => unknown;
+
+/**
+ * The configuration for a reference property — which model it points to and how
+ * the relationship behaves.
+ */
+export interface ReferenceMetadata {
+  referencedModel: () => ModelConstructor;
+  backReference?: string;
+  indexed?: boolean;
+  nullable?: boolean;
+}
+
+/**
+ * The resolved configuration for a model class.
+ */
+export interface ModelMetadata {
+  loadStrategy: LoadStrategy;
+  syncGroup?: string;
+  tableName?: string;
+  schemaVersion?: number;
+  /**
+   * The schema-declared fields for this model, keyed by field name. When a
+   * change is committed, the transaction queue uses this to project the payload
+   * down to the declared fields and to serialize JSON-typed values.
+   *
+   * Each entry carries the field's {@link FieldMeta.type} tag, which tells the
+   * wire serializer how to encode the value. When this is absent — a model
+   * registered without a schema — the payload is passed through unchanged.
+   */
+  fields?: Readonly<Record<string, Pick<FieldMeta, 'type'>>>;
+  /**
+   * Fields to fill in from the signed-in identity when they are missing from a
+   * stored row during self-healing. Each entry maps a field on this model to
+   * one of the identity values the client holds — `organizationId` or `userId`.
+   * Declaring it in the schema keeps the engine product-neutral: it does not
+   * assume which models carry an organization or owner field.
+   */
+  autoFill?: readonly { field: string; from: 'organizationId' | 'userId' }[];
+  /**
+   * Fields a stored row must have to be usable. During self-healing, a row
+   * missing any of these is treated as orphaned and skipped rather than loaded.
+   */
+  requiredFields?: readonly string[];
+}
+
+/**
+ * The options accepted when declaring a model — its load strategy, optional
+ * sync group, and optional table name.
+ */
+export interface ModelOptions {
+  loadStrategy: LoadStrategy;
+  syncGroup?: string;
+  tableName?: string;
+}
+
+/**
+ * The options accepted when declaring a model property.
+ */
+export interface PropertyOptions {
+  indexed?: boolean;
+  optional?: boolean;
+  defaultValue?: unknown;
+  ephemeral?: boolean;
+}
+
+/**
+ * The options accepted when declaring a reference property.
+ */
+export interface ReferenceOptions {
+  indexed?: boolean;
+  nullable?: boolean;
+}
+
+/**
+ * A request to load model rows by an indexed key. When the load completes,
+ * `resolve` is called with the matching rows.
+ */
+export interface LoadRequest {
+  modelName: string;
+  indexedKey: string;
+  keyValue: string;
+  resolve?: (value: unknown[]) => void;
+}
+
+/**
+ * How a session establishes its baseline state at startup.
+ *
+ * 'full' — Fetch a complete snapshot from the server, clear the local store,
+ *   load the snapshot, and adopt its `lastSyncId`.
+ *
+ * 'partial' — Fetch only the deltas since the stored `lastSyncId` and apply
+ *   them on top of the existing local data.
+ *
+ * 'local' — Skip the server entirely: hydrate the instance cache from the local
+ *   store, connect the WebSocket with the stored `lastSyncId`, and receive
+ *   deltas from there onward. Used when offline with valid local data.
+ */
+export type BootstrapType = 'full' | 'partial' | 'local';
+
+/**
+ * The metadata returned with a bootstrap: the last sync id seen and the sync
+ * groups the client is subscribed to.
+ */
+export interface BootstrapMetadata {
+  lastSyncId: number;
+  subscribedSyncGroups: string[];
+}
+
+/**
+ * The locally tracked sync state that lets a client resume where it left off.
+ */
+export interface DatabaseMetadata {
+  lastSyncId: number; // Current sync version
+  firstSyncId: number; // Sync version captured at bootstrap
+  backendDatabaseVersion: number;
+  subscribedSyncGroups: string[]; // Sync groups this client is subscribed to
+  updatedAt: Date;
+}
+
+/**
+ * The operation a batch mutation performs on a model row.
+ */
+export enum MutationOperationType {
+  ARCHIVE = 'ARCHIVE',
+  CREATE = 'CREATE',
+  DELETE = 'DELETE',
+  UNARCHIVE = 'UNARCHIVE',
+  UPDATE = 'UPDATE',
+}
+
+/**
+ * Describes a partial index used to load subsets of a large model.
+ */
+export interface PartialIndexInfo {
+  modelName: string;
+  indexKey: string;
+  depth: number; // 1-3 levels deep
+  path: string[];
+}
+
+// Re-export the stream, snapshot, and coordination types that make up the
+// engine's public surface (PresenceStream, ClaimStream, Snapshot, and the
+// rest), reached through `Ablo({...}).presence`, `.claims`, and `.snapshot()`.
+//
+// The list is written out by name rather than `export *` so that adding a
+// symbol here is always a deliberate decision, and new types don't become
+// public API by accident.
+export type {
+  // Coordination wire shapes, defined in `../coordination/schema` and
+  // re-exported through streams.ts.
+  OnStaleMode,
+  WireClaim,
+  ClaimRejection,
+  PresenceKind,
+  ParticipantKind,
+  // Participant identity, defined in `./participant.ts`.
+  ParticipantRef,
+  // Streams' own types.
+  JsonValue,
+  ConfirmationState,
+  Delta,
+  AgentDelta,
+  Snapshot,
+  ContextChange,
+  ClaimTarget,
+  PresenceTarget,
+  PresenceStream,
+  Activity,
+  Peer,
+  PresenceUpdatePayload,
+  ClaimLeaseOptions,
+  Duration,
+  ClaimOptions,
+  ClaimStream,
+  ClaimLost,
+  ClaimStatus,
+  ClaimWaitOptions,
+  Claim,
+  HeldClaim,
+} from './streams.js';

package/src/types/modelData.ts

@@ -0,0 +1,11 @@
+/**
+ * The generic record shape for a model's data — a map from field name to value.
+ *
+ * Because the values are typed as `unknown`, read the data as the
+ * schema-inferred entity type rather than accessing fields off this shape
+ * directly. It has no imports of its own, so any module can depend on it
+ * without creating an import cycle.
+ */
+
+/** A record mapping each model field name to its value. */
+export type ModelData = Record<string, unknown>;

package/src/types/participant.ts

@@ -0,0 +1,22 @@
+/**
+ * The identity of a participant — a person's session, an AI agent, or a system
+ * actor — in the coordination protocol.
+ *
+ * {@link ParticipantRef} is the single identity shape shared by the streams
+ * types and the conflict-policy types. It has no imports of its own, so both
+ * can depend on it without creating an import cycle. The runtime validator for
+ * the same participant kinds lives alongside the other coordination schemas.
+ */
+
+/** The kind of actor a participant is: a human session, an AI agent, or a system actor. */
+export type ParticipantKind = 'user' | 'agent' | 'system';
+
+/**
+ * A reference to one participant: its {@link ParticipantKind} and its id. Used
+ * both for the actor performing an action and for the participant it acts on
+ * behalf of.
+ */
+export interface ParticipantRef {
+  kind: ParticipantKind;
+  id: string;
+}