@abloatai/ablo 0.25.0 → 0.27.0

package/dist/client/claimHeartbeatLoop.js

@@ -0,0 +1,88 @@
+/**
+ * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
+ * implementation shared by both transports (the WebSocket claim stream and the
+ * HTTP `ApiClient`), so the cadence and failure semantics cannot drift.
+ *
+ * A beat is the "still working" signal that keeps a lease alive for the
+ * duration of real work. The loop's failure handling follows the lease-system
+ * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
+ * for a transient reason — the network blipped, the server was briefly
+ * unavailable — is simply retried on the next tick, because the lease has
+ * runway to spare by construction (the default cadence is a third of the TTL,
+ * so two consecutive beats can fail before the lease is even at risk). Only a
+ * definitive answer from the server — the lease lapsed and may have been
+ * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
+ * surfaces the loss, because for a caller with no push channel the failed beat
+ * IS the loss notification.
+ */
+import { AbloClaimedError } from '../errors.js';
+import { toMs } from '../utils/duration.js';
+/**
+ * Normalize the public `heartbeat(options?)` argument — a bare Duration is
+ * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
+ * shorthand cannot drift.
+ */
+export function resolveHeartbeatOptions(input) {
+    if (input === undefined)
+        return {};
+    if (typeof input === 'string' || typeof input === 'number') {
+        return { ttl: input };
+    }
+    return input;
+}
+/**
+ * The beat cadence for a lease of `ttlMs`: an explicit duration when the
+ * caller set one, otherwise a third of the TTL (floored at 1s) — the
+ * DynamoDB-lock-client rule, leaving two missed beats of runway before the
+ * lease is at risk while keeping crash recovery within one beat window.
+ */
+export function heartbeatCadenceMs(ttlMs, heartbeat) {
+    if (heartbeat !== true)
+        return toMs(heartbeat);
+    return Math.max(Math.floor(ttlMs / 3), 1_000);
+}
+/**
+ * Start beating. Returns a stop function; callers stop the loop when the
+ * claim is released (all held-claim assembly sites tie this to `release`).
+ * Beats never overlap: a tick that fires while the previous beat is still
+ * in flight is skipped rather than stacked.
+ */
+export function startClaimHeartbeatLoop(options) {
+    let stopped = false;
+    let inFlight = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+    };
+    const timer = setInterval(() => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        options
+            .beat()
+            .catch((error) => {
+            if (stopped)
+                return;
+            if (error instanceof AbloClaimedError) {
+                stop();
+                options.onLost?.(error);
+                return;
+            }
+            // Transient (connection, brief server unavailability): the next tick
+            // is the retry — the ttl/3 cadence leaves runway for missed beats.
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    }, options.intervalMs);
+    // The loop must never be what keeps a Node process alive — the held work
+    // is. A worker that finishes without releasing exits anyway, and the lease
+    // lapses on schedule. No-op in browsers (where setInterval returns a number
+    // without `unref`), which is why the call is optional even though the Node
+    // timer type always has it.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    timer.unref?.();
+    return stop;
+}

package/dist/client/consoleLogger.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The default `[Ablo]` console logger and its level resolution.
+ *
+ * These helpers are exported so any entry point that needs a default logger can
+ * reuse the same level gating rather than hand-rolling a console wrapper.
+ */
+import type { SyncLogger } from '../interfaces/index.js';
+/**
+ * Level threshold for the default console logger.
+ *
+ * The SDK emits a `debug` line per model and per property during schema
+ * registration (see `ModelRegistry`), plus assorted lifecycle chatter. That
+ * is verbose by design but carries no actionable signal for app consumers, so
+ * the default threshold is `warn` — `debug`/`info` are dropped unless a
+ * consumer opts in.
+ *
+ * Opt back in with `ABLO_LOG_LEVEL=debug` (or `info`/`warn`/`error`/`silent`).
+ * Passing a custom `logger` to `Ablo({ logger })` bypasses this entirely.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+export declare function resolveLogLevel(opts?: {
+    debug?: boolean;
+    logLevel?: LogLevel;
+}): LogLevel;
+/**
+ * Builds the default logger, gated at `level` and prefixed `[Ablo]` so its lines
+ * stand out in a console full of other tools' output.
+ */
+export declare function createConsoleLogger(level: LogLevel): SyncLogger;

package/dist/client/consoleLogger.js

@@ -0,0 +1,44 @@
+/**
+ * The default `[Ablo]` console logger and its level resolution.
+ *
+ * These helpers are exported so any entry point that needs a default logger can
+ * reuse the same level gating rather than hand-rolling a console wrapper.
+ */
+const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
+/**
+ * Resolve the effective level. Precedence: explicit `logLevel` option →
+ * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
+ * / omitted just means "don't raise the level" — it falls through to env/default
+ * rather than force-silencing an ops-set env override.
+ */
+export function resolveLogLevel(opts) {
+    if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK)
+        return opts.logLevel;
+    if (opts?.debug === true)
+        return 'debug';
+    // `globalThis.process` guard keeps this safe in browser/edge runtimes that
+    // have no `process` binding — there we fall through to the default.
+    const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
+    const normalized = raw?.toLowerCase();
+    if (normalized && normalized in LOG_LEVEL_RANK)
+        return normalized;
+    return 'warn';
+}
+/**
+ * Builds the default logger, gated at `level` and prefixed `[Ablo]` so its lines
+ * stand out in a console full of other tools' output.
+ */
+export function createConsoleLogger(level) {
+    const threshold = LOG_LEVEL_RANK[level];
+    const emit = (lvl, fn, args) => {
+        if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold)
+            return;
+        fn('[Ablo]', ...args);
+    };
+    return {
+        debug: (...args) => { emit('debug', console.debug, args); },
+        info: (...args) => { emit('info', console.info, args); },
+        warn: (...args) => { emit('warn', console.warn, args); },
+        error: (...args) => { emit('error', console.error, args); },
+    };
+}

package/dist/client/createInternalComponents.d.ts

@@ -1,28 +1,25 @@
 /**
- * Internal component construction for `Ablo()`.
+ * Builds the internal component graph the client runs on.
  *
- * Builds the full sync-engine component graph from options + schema:
- * `ModelRegistry`, `ObjectPool`, `BootstrapHelper`, `Database`,
- * `SyncClient`, `HydrationCoordinator`. Each component depends on
- * the previous one, so the construction order matters; isolating it
- * here means `Ablo.ts` doesn't need to know the dependency order.
- *
- * Mirrors the pattern Anthropic uses: their client constructor wires
- * endpoint modules. Ours wires the sync-engine components instead.
+ * From the caller's options and schema this wires together the model registry,
+ * object pool, bootstrap helper, database, sync client, and hydration
+ * coordinator. Each component depends on the one before it, so construction
+ * order matters; keeping it here means the client constructor does not have to
+ * know that order.
  */
 import { Database } from '../Database.js';
 import { ModelRegistry } from '../ModelRegistry.js';
-import { ObjectPool } from '../ObjectPool.js';
+import { InstanceCache } from '../InstanceCache.js';
 import { SyncClient } from '../SyncClient.js';
-import { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
-import { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import { OnDemandLoader } from '../sync/OnDemandLoader.js';
+import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import { type AbloPersistence } from './persistence.js';
 export interface InternalComponentsInput<S extends SchemaRecord> {
     readonly schema: Schema<S>;
-    /** WebSocket URL — used to derive bootstrap HTTP base when the
-     * caller didn't override `bootstrapBaseUrl`. */
+    /** The WebSocket URL. Used to derive the bootstrap HTTP base URL when the
+     * caller has not overridden `bootstrapBaseUrl`. */
     readonly url: string;
     readonly options: {
         readonly maxPoolSize?: number;
@@ -36,10 +33,10 @@ export interface InternalComponentsInput<S extends SchemaRecord> {
 }
 export interface InternalComponents {
     readonly modelRegistry: ModelRegistry;
-    readonly objectPool: ObjectPool;
-    readonly bootstrapHelper: BootstrapHelper;
+    readonly objectPool: InstanceCache;
+    readonly bootstrapHelper: BootstrapFetcher;
     readonly database: Database;
     readonly syncClient: SyncClient;
-    readonly hydration: HydrationCoordinator;
+    readonly hydration: OnDemandLoader;
 }
 export declare function createInternalComponents<S extends SchemaRecord>(input: InternalComponentsInput<S>): InternalComponents;

package/dist/client/createInternalComponents.js

@@ -1,56 +1,52 @@
 /**
- * Internal component construction for `Ablo()`.
+ * Builds the internal component graph the client runs on.
  *
- * Builds the full sync-engine component graph from options + schema:
- * `ModelRegistry`, `ObjectPool`, `BootstrapHelper`, `Database`,
- * `SyncClient`, `HydrationCoordinator`. Each component depends on
- * the previous one, so the construction order matters; isolating it
- * here means `Ablo.ts` doesn't need to know the dependency order.
- *
- * Mirrors the pattern Anthropic uses: their client constructor wires
- * endpoint modules. Ours wires the sync-engine components instead.
+ * From the caller's options and schema this wires together the model registry,
+ * object pool, bootstrap helper, database, sync client, and hydration
+ * coordinator. Each component depends on the one before it, so construction
+ * order matters; keeping it here means the client constructor does not have to
+ * know that order.
  */
 import { Database } from '../Database.js';
 import { ModelRegistry, setActiveRegistry } from '../ModelRegistry.js';
-import { ObjectPool } from '../ObjectPool.js';
+import { InstanceCache } from '../InstanceCache.js';
 import { SyncClient } from '../SyncClient.js';
-import { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
-import { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import { OnDemandLoader } from '../sync/OnDemandLoader.js';
+import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import { resolveBootstrapBaseUrl } from './auth.js';
 import { shouldUseInMemoryPersistence } from './persistence.js';
 export function createInternalComponents(input) {
     const { schema, url, options, auth } = input;
-    // The registry is created here but model registration happens in
-    // the caller (Ablo.ts owns `registerModelsFromSchema` since the
-    // schema-to-class translation depends on private helpers there).
+    // The registry is created here, but model registration happens in the caller,
+    // which owns the schema-to-class translation.
     const modelRegistry = new ModelRegistry({
         validateOnRegister: false,
         allowLateReferences: true,
     });
     setActiveRegistry(modelRegistry);
-    const objectPool = new ObjectPool({ maxSize: options.maxPoolSize ?? 10000 }, modelRegistry);
+    const objectPool = new InstanceCache({ maxSize: options.maxPoolSize ?? 10000 }, modelRegistry);
     const bootstrapBaseUrl = resolveBootstrapBaseUrl({
         url,
         bootstrapBaseUrl: options.bootstrapBaseUrl,
     });
-    const bootstrapHelper = new BootstrapHelper({
+    const bootstrapHelper = new BootstrapFetcher({
         baseUrl: bootstrapBaseUrl,
         syncGroups: options.syncGroups,
         instantModels: deriveInstantModels(schema),
         getAuthToken: auth?.getAuthToken,
     });
     const database = new Database(modelRegistry, bootstrapHelper, {
-        // Point-solution default: no browser-local durable store unless the
-        // caller explicitly asks for it. Node/edge runtimes always use the
-        // in-memory store because IndexedDB is unavailable there.
+        // By default there is no browser-local durable store unless the caller asks
+        // for one. Node and edge runtimes always use the in-memory store because
+        // IndexedDB is unavailable there.
         inMemory: shouldUseInMemoryPersistence(options),
     });
     const syncClient = new SyncClient(objectPool, database);
-    // Lazy-load lane: hydrates pool/IDB on `ablo.<model>.load(...)` for
-    // entities not in scope at bootstrap (`load: 'lazy'` models, or
-    // entities accessed via deep-link before the pool warmed up).
-    // Single-flight + IDB write-through.
-    const hydration = new HydrationCoordinator({
+    // Lazy-load lane: hydrates the object pool and IndexedDB on demand for
+    // entities not in scope at bootstrap (`load: 'lazy'` models, or an entity
+    // reached by deep link before the pool warmed up). Single-flight, with
+    // write-through to IndexedDB.
+    const hydration = new OnDemandLoader({
         objectPool,
         database,
         registry: modelRegistry,
@@ -62,7 +58,7 @@ export function createInternalComponents(input) {
     // WebSocket delta stream keeps hydrated rows fresh so repeat reads serve
     // pure-local with no network; after a drop, deltas may have been missed, so
     // the next read of each query must re-confirm with the server once.
-    syncClient.on('sync:reconnecting', () => hydration.invalidate());
+    syncClient.on('sync:reconnecting', () => { hydration.invalidate(); });
     return {
         modelRegistry,
         objectPool,
@@ -73,11 +69,10 @@ export function createInternalComponents(input) {
     };
 }
 /**
- * Derive instant-bootstrap model names from schema load strategies.
- * Models with `load: 'lazy'` or `'manual'` are excluded from the
- * initial bootstrap request — they're fetched on demand by the
- * `ensure*` loaders or (Phase 6) by the `ObjectPool` auto-fetch
- * mechanism. Default load strategy is `'instant'`.
+ * Derives the set of models to fetch in the initial bootstrap request from each
+ * model's load strategy. Models declared `load: 'lazy'` or `'manual'` are left
+ * out of the bootstrap and fetched on demand instead. The default strategy is
+ * `'instant'`, which includes the model.
  */
 function deriveInstantModels(schema) {
     const schemaModels = schema.models ?? schema;