@alneas/eaos-server API

@alneas/eaos-server API

Public entrypoints

Import	Contract
@alneas/eaos-server/db/local-first-sqlite-adapter	Typed public export
@alneas/eaos-server/db	Typed public export
@alneas/eaos-server/db/migration/aggregator	Typed public export
@alneas/eaos-server/db/migration	Typed public export

[INTERFACE] AccessFrequencyRecord

Per-table local counters used to rank adaptive synchronization candidates.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

interface AccessFrequencyRecord {
    table_name: string;
    read_count: number;
    write_count: number;
    last_accessed_at: string;
}

Parameters

Name	Type	Required	Description
table_name	string	Yes	Tracked collection identifier.
read_count	number	Yes	Accumulated read count.
write_count	number	Yes	Accumulated write count.
last_accessed_at	string	Yes	ISO timestamp of the most recently recorded access.

Returns

Type declaration; no runtime value.

See also

LocalFirstSqliteAdapter.recordAccess.

Public members

table_name

Tracked collection identifier.

read_count

Accumulated read count.

write_count

Accumulated write count.

last_accessed_at

ISO timestamp of the most recently recorded access.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] assertDataContractBinding

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

declare function assertDataContractBinding(catalog: DataContractCatalog, binding: DataContractBinding): void;

Parameters

Name	Type	Required	Description
catalog	DataContractCatalog	Yes	See the upstream owning declaration.
binding	DataContractBinding	Yes	See the upstream owning declaration.

Returns

void

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] assertJsonDocumentContracts

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

declare function assertJsonDocumentContracts(documents: readonly JsonDocumentContract[], tables: ReadonlyMap<string, Record<string, unknown>>): void;

Parameters

Name	Type	Required	Description
documents	readonly JsonDocumentContract[]	Yes	See the upstream owning declaration.
tables	ReadonlyMap<string, Record<string, unknown>>	Yes	See the upstream owning declaration.

Returns

void

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] collectSchemaMigrations

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

declare function collectSchemaMigrations(releases: readonly SchemaMigrationSource[], available?: readonly DataContract[]): PluginMigration[];

Parameters

Name	Type	Required	Description
releases	readonly SchemaMigrationSource[]	Yes	See the upstream owning declaration.
available	readonly DataContract[]	No	See the upstream owning declaration.

Returns

PluginMigration[]

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] ConnectionStats

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface ConnectionStats {
    activeConnections: number;
    poolSize: number;
    driver: DbDriverType;
}

Parameters

Name	Type	Required	Description
activeConnections	number	Yes	See the upstream owning declaration.
poolSize	number	Yes	See the upstream owning declaration.
driver	DbDriverType	Yes	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] createJsonDocumentAssertion

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

declare function createJsonDocumentAssertion(document: JsonDocumentContract): (value: unknown) => void;

Parameters

Name	Type	Required	Description
document	JsonDocumentContract	Yes	See the upstream owning declaration.

Returns

(value: unknown) => void

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] DatabaseAdapter

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface DatabaseAdapter {
    readonly type: DbDriverType;
    withConnection<T>(domain: string, callback: (connection: any) => Promise<T>): Promise<T>;
    withTenantConnection<T>(domain: string, callback: (connection: any) => Promise<T>, context: TenantSessionContext): Promise<T>;
    ping(): Promise<boolean>;
    getStats(): ConnectionStats;
    close(): Promise<void>;
}

Parameters

Name	Type	Required	Description
type	DbDriverType	Yes	See the upstream owning declaration.
withConnection	Promise<T>	Yes	See the upstream owning declaration.
withTenantConnection	Promise<T>	Yes	See the upstream owning declaration.
ping	Promise<boolean>	Yes	See the upstream owning declaration.
getStats	ConnectionStats	Yes	See the upstream owning declaration.
close	Promise<void>	Yes	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] DataContract

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface DataContract {
    id: string;
    version: string;
    description: string;
    schema: Record<string, unknown>;
    migrations: PluginMigration[];
    dependencies?: Record<string, string>;
    migrationIdentity?: string;
    jsonDocuments?: JsonDocumentContract[];
}

Parameters

Name	Type	Required	Description
id	string	Yes	See the upstream owning declaration.
version	string	Yes	See the upstream owning declaration.
description	string	Yes	See the upstream owning declaration.
schema	Record<string, unknown>	Yes	See the upstream owning declaration.
migrations	PluginMigration[]	Yes	See the upstream owning declaration.
dependencies	Record<string, string>	No	See the upstream owning declaration.
migrationIdentity	string	No	See the upstream owning declaration.
jsonDocuments	JsonDocumentContract[]	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] DataContractBinding

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface DataContractBinding {
    contractId: string;
    version: string;
    table: string;
    namespace?: string;
}

Parameters

Name	Type	Required	Description
contractId	string	Yes	See the upstream owning declaration.
version	string	Yes	See the upstream owning declaration.
table	string	Yes	See the upstream owning declaration.
namespace	string	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] DataContractCatalog

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface DataContractCatalog {
    contracts: DataContract[];
    tables: {
        name: string;
        contractId: string;
        version: string;
        schema: Record<string, unknown>;
    }[];
}

Parameters

Name	Type	Required	Description
contracts	DataContract[]	Yes	See the upstream owning declaration.
tables	{ name: string; contractId: string; version: string; schema: Record<string, unknown>; }[]	Yes	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] dataContractTables

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

declare function dataContractTables(schema: Record<string, unknown>): Map<string, Record<string, unknown>>;

Parameters

Name	Type	Required	Description
schema	Record<string, unknown>	Yes	See the upstream owning declaration.

Returns

Map<string, Record<string, unknown>>

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] JsonDocumentContract

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface JsonDocumentContract {
    id: string;
    version: string;
    table: string;
    column: string;
    namespace?: string;
    jsonPath?: string;
    recordPrefix?: string;
    schema: Record<string, unknown>;
    immutable?: boolean;
    maxBytes?: number;
}

Parameters

Name	Type	Required	Description
id	string	Yes	See the upstream owning declaration.
version	string	Yes	See the upstream owning declaration.
table	string	Yes	See the upstream owning declaration.
column	string	Yes	See the upstream owning declaration.
namespace	string	No	See the upstream owning declaration.
jsonPath	string	No	See the upstream owning declaration.
recordPrefix	string	No	See the upstream owning declaration.
schema	Record<string, unknown>	Yes	See the upstream owning declaration.
immutable	boolean	No	See the upstream owning declaration.
maxBytes	number	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] LocalFirstSqliteAdapter

Persists local mutations and an outbox, then synchronizes with a host-provided upstream adapter.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

declare class LocalFirstSqliteAdapter implements DataAccessAdapter {
    readonly tenantId?: string;
    constructor(options: LocalFirstSqliteAdapterOptions);
    initSchema(): Promise<void>;
    recordAccess(collection: string, type: 'read' | 'write'): Promise<void>;
    syncActiveTables(limit?: number): Promise<string[]>;
    find<T = unknown>(collection: string, filter?: Filter, options?: QueryOptions): Promise<T[]>;
    count(collection: string, filter?: Filter, options?: QueryOptions): Promise<number>;
    findOne<T = unknown>(collection: string, id: string, options?: QueryOptions): Promise<T | null>;
    create<T = unknown>(collection: string, data: Record<string, unknown>, _options?: QueryOptions): Promise<T>;
    update<T = unknown>(collection: string, id: string, data: Record<string, unknown>, _options?: QueryOptions): Promise<T>;
    delete<T = unknown>(collection: string, id: string, _options?: QueryOptions): Promise<T>;
    pullChanges(collection: string): Promise<number>;
    processOutbox(): Promise<void>;
    destroy(): void;
}

Parameters

Name	Type	Required	Description
options	LocalFirstSqliteAdapterOptions	Yes	Host drivers and synchronization settings; see {@link LocalFirstSqliteAdapterOptions}.

Returns

LocalFirstSqliteAdapter

Remarks

Call initSchema before use; it creates metadata only, so provision domain tables separately. Local mutation and outbox insertion are separate writes, so failure may leave an unqueued local change. No tenant authorization is implemented: tenantId is only a create default. Serialize transaction-sensitive operations on the host driver; processOutbox excludes overlapping calls on this instance only. Call destroy to remove timers/listeners; it does not cancel in-flight work or close either driver.

Constructor contract

Remarks

The constructor performs no schema initialization. Timers/listeners start immediately unless disabled; call destroy when the instance is no longer needed.

Public members

tenantId

Optional create-time tenant_id fallback captured from options; not a read or mutation authorization filter.

initSchema

Initializes SQLite synchronization metadata tables and attempts WAL, NORMAL, and 5000 ms busy-timeout pragmas.

Returns: No value; resolves after metadata table creation. Pragma failures are deliberately ignored.

Errors and rejections

Rejects metadata table creation failures; earlier tables may already exist.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    await adapter.initSchema();
  } finally { adapter.destroy(); }
}

recordAccess

Increments a table read or write counter and records the current ISO timestamp.

Parameters:

• collection: Table name recorded as a metadata value.
• type: Counter to increment; read contributes weight 2 and write weight 5 in adaptive ranking.

Returns: No value; resolves after the counter upsert.

Errors and rejections

Rejects SQLite failures.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    await adapter.recordAccess("records", "read");
  } finally { adapter.destroy(); }
}

syncActiveTables

Pulls every essential table plus the highest weighted access-frequency tables sequentially.

Parameters:

• limit: Maximum frequency-ranked tables selected in addition to essential tables; defaults to 8 and is passed to SQLite without additional validation.

Returns: Names whose pullChanges calls completed, including tables with no new rows; failed tables are warned and omitted.

Errors and rejections

Rejects the initial frequency query failure; individual pull failures are caught.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.syncActiveTables(8);
  } finally { adapter.destroy(); }
}

find

Queries local SQLite rows and schedules a best-effort read-frequency update.

Parameters:

• collection: Local table identifier, quoted by the adapter.
• filter: AND-combined equality/null or $eq/$gt/$gte/$lt/$lte column conditions; other operator objects are rejected.
• options: Supports sort, limit, and skip; limit/skip must be nonnegative safe integers. Projection and other options are ignored.

Returns: Local rows, or an empty array; remote freshness is not implied.

Type parameters

• T: Expected local row shape; no runtime schema validation is performed.

Errors and rejections

Rejects unsupported filters, invalid pagination, or SQLite query failures. Access-stat failures are ignored.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.find("records", { active: true }, { limit: 10 });
  } finally { adapter.destroy(); }
}

count

Counts local rows matching a filter without pagination.

Parameters:

• collection: Local table identifier, quoted by the adapter.
• filter: Same supported AND-combined conditions as find.
• options: Sort is retained; limit and skip are discarded. Other options are ignored.

Returns: Numeric count, or zero if the driver returns no count row.

Errors and rejections

Rejects unsupported filters or SQLite failures; access-stat failures are ignored.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.count("records");
  } finally { adapter.destroy(); }
}

findOne

Queries a local row by its id column.

Parameters:

• collection: Local table identifier.
• id: ID value bound to an equality filter.
• options: find options with limit overridden to 1; skip, if supplied, still applies.

Returns: First matching row, or null.

Type parameters

• T: Expected local row shape; no runtime validation is performed.

Errors and rejections

Rejects invalid pagination or SQLite query failures.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.findOne("records", "record-1");
  } finally { adapter.destroy(); }
}

create

Inserts a local record before separately enqueueing its upstream INSERT.

Parameters:

• collection: Provisioned local table identifier.
• data: Column values; a truthy id is retained, otherwise an ID is generated. Missing tenant columns may receive the configured tenantId. Object values are JSON-encoded for local SQL.
• _options: Accepted for DataAccessAdapter compatibility and ignored.

Returns: The input record with its chosen ID and optional tenant default, before upstream acknowledgement.

Type parameters

• T: Expected returned record shape; no runtime validation is performed.

Errors and rejections

Rejects local SQL, serialization, or enqueue failure; a local insert may already have committed. Background outbox errors are ignored by this call.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.create("records", { title: "Example" });
  } finally { adapter.destroy(); }
}

update

Snapshots a local row, updates its columns, and separately enqueues an upstream UPDATE.

Parameters:

• collection: Provisioned local table identifier.
• id: Record ID bound in local SQL and used for upstream update.
• data: Updated columns; local SQL excludes id but the payload is forwarded unchanged upstream. An empty update can cause a SQLite syntax failure.
• _options: Accepted for DataAccessAdapter compatibility and ignored.

Returns: Snapshot merged with data and the supplied id, even if no local row existed.

Type parameters

• T: Expected returned merged record shape.

Errors and rejections

Rejects snapshot, local SQL, serialization, or enqueue failures; local changes may already have committed.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.update("records", "record-1", { title: "Changed" });
  } finally { adapter.destroy(); }
}

delete

Deletes a local row and separately enqueues upstream deletion with a rollback snapshot.

Parameters:

• collection: Provisioned local table identifier.
• id: Record ID used for local and upstream deletion.
• _options: Accepted for DataAccessAdapter compatibility and ignored.

Returns: The previous local record, or an object containing only id when absent.

Type parameters

• T: Expected deleted record shape.

Errors and rejections

Rejects snapshot, local delete, or enqueue failures; local deletion may already have committed.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.delete("records", "record-1");
  } finally { adapter.destroy(); }
}

pullChanges

Pulls incremental remote changes from Oracle ADB using ORA_ROWSCN cursor within a batch transaction.

Parameters:

• collection: Provisioned local table whose upstream supports ORA_ROWSCN filtering, ordering, and projection.

Returns: Number of remote rows upserted, or zero when no changes were returned.

Remarks

Remote deletes are not discovered by this pull. No per-table synchronization lock prevents overlapping pulls or concurrent host transactions.

Errors and rejections

Rejects upstream or local SQL failures; an opened local transaction is rolled back best-effort on upsert/cursor failure.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.pullChanges("records");
  } finally { adapter.destroy(); }
}

processOutbox

Background Outbox Worker: Processes at most 20 pending mutations in creation order, pushes upstream, and attempts rollback for non-network failures.

Returns: No value; resolves after one batch, or immediately if this instance already has a batch running.

Remarks

Recognized network failures return rows to pending and increment retry_count; no delay/backoff is applied here. Other failures attempt local snapshot rollback and mark failed; rollback/callback errors are logged. Remote success followed by local queue-delete failure may leave an uncertain delivery outcome. There is no cross-instance lease or deduplication.

Errors and rejections

Rejects metadata reads, malformed persisted JSON, or error-handling SQL failures. Ordinary upstream failures are recorded or rolled back rather than rejected.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    await adapter.processOutbox();
  } finally { adapter.destroy(); }
}

destroy

Stops this instance’s polling timer and removes its browser focus/online listeners.

Returns: No value; repeated calls are safe. In-flight synchronization continues and drivers remain open.

Example:

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    adapter.destroy();
  } finally { adapter.destroy(); }
}

Example

import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
export async function example(options: LocalFirstSqliteAdapterOptions) {
  // The host supplies an initialized domain schema and authorized upstream adapter.
  const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
  try {
    await adapter.initSchema();
    return await adapter.find("records");
  } finally { adapter.destroy(); }
}

[INTERFACE] LocalFirstSqliteAdapterOptions

Host drivers, sync behavior, and cleanup-sensitive scheduling for LocalFirstSqliteAdapter.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

interface LocalFirstSqliteAdapterOptions {
    sqlite: SqliteDriver;
    upstream: DataAccessAdapter;
    tenantId?: string;
    essentialTables?: string[];
    onSyncError?: (event: SyncErrorEvent) => void;
    syncIntervalMs?: number;
    autoSyncOnMutation?: boolean;
    enableLifecycleSync?: boolean;
}

Parameters

Name	Type	Required	Description
sqlite	SqliteDriver	Yes	SQLite driver instance
upstream	DataAccessAdapter	Yes	Cloud upstream adapter (e.g. OracleOrdsAdapter / SupabaseAdapter)
tenantId	string	No	Optional tenant_id default added only on create when neither tenant_id nor tenantId is supplied; this does not scope reads, updates, deletes, or upstream access. Host authorization remains required.
essentialTables	string[]	No	Essential master tables that are always synchronized (Tier 1)
onSyncError	(event: SyncErrorEvent) => void	No	Callback fired when an outbox sync fails permanently and triggers a rollback
syncIntervalMs	number	No	Outbox polling interval in milliseconds. Zero disables polling; other falsy values fall back to 5000.
autoSyncOnMutation	boolean	No	Whether to immediately trigger background sync after local mutation (default: true)
enableLifecycleSync	boolean	No	Whether to attach window focus / online event listeners (default: true if in browser/tauri)

Returns

Type declaration; no runtime value.

Public members

sqlite

SQLite driver instance

upstream

Cloud upstream adapter (e.g. OracleOrdsAdapter / SupabaseAdapter)

tenantId

Optional tenant_id default added only on create when neither tenant_id nor tenantId is supplied; this does not scope reads, updates, deletes, or upstream access. Host authorization remains required.

essentialTables

Essential master tables that are always synchronized (Tier 1)

onSyncError

Callback fired when an outbox sync fails permanently and triggers a rollback

syncIntervalMs

Outbox polling interval in milliseconds. Zero disables polling; other falsy values fall back to 5000.

Default: 5000.

autoSyncOnMutation

Whether to immediately trigger background sync after local mutation (default: true)

enableLifecycleSync

Whether to attach window focus / online event listeners (default: true if in browser/tauri)

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[CLASS] MigrationAggregator

Collects plugin schema sources and renders legacy PostgreSQL or Oracle DDL text.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/migration, @alneas/eaos-server/db/migration/aggregator.

Signature

declare class MigrationAggregator {
    constructor(plugins: PluginManifest[], dataContracts?: DataContract[]);
    collectSchemas(resolveSchema: (pluginId: string, extensionId?: string) => Record<string, any> | null): SchemaSource[];
    generatePostgres(sources: SchemaSource[], dbDriver?: string): string;
    generateOracle(sources: SchemaSource[]): string;
}

Parameters

Name	Type	Required	Description
plugins	PluginManifest[]	Yes	Manifests consulted on every collection call; the array is retained rather than cloned.
dataContracts	DataContract[]	No	Available contracts used to resolve manifest requirements; defaults to none and is retained.

Returns

MigrationAggregator

Remarks

Generation never executes SQL. Schema identifiers, defaults, and comments are interpolated from trusted schema inputs; review generated SQL before applying it. Canonical data-contract JSON Schema requires reviewed lifecycle migrations rather than these legacy converters.

Constructor contract

Public members

collectSchemas

Collects resolved data contracts first, then plugin and extension schemas by migration order.

Parameters:

• resolveSchema: Called with plugin ID and optional extension ID; returns a legacy schema or null to skip it. Plugin schemas declaring data contracts skip the plugin-level callback, but extensions are still resolved.

Returns: Ordered schema sources; manifests with equal order retain their sort order and missing callback results are omitted.

Errors and rejections

Propagates contract resolution or callback errors.

Example:

import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
const aggregator = new MigrationAggregator([]);
console.log(aggregator.collectSchemas(() => null)); // []

generatePostgres

Renders PostgreSQL table DDL and tenant_id row-level-security policies as text.

Parameters:

• sources: Trusted legacy schemas rendered in supplied order. Every table must declare tenant_id not explicitly nullable.
• dbDriver: Label included in SQL comments only; defaults to postgres and does not change dialect.

Returns: SQL text with a generated timestamp, CREATE TABLE IF NOT EXISTS, and tenant policies using app.current_tenant as UUID.

Remarks

The host must set app.current_tenant appropriately and review/apply SQL separately.

Errors and rejections

For canonical x-db/$defs schemas or missing/nullable tenant_id columns.

Example:

import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
const aggregator = new MigrationAggregator([]);
console.log(aggregator.generatePostgres([]));

generateOracle

Renders legacy Oracle table DDL as text.

Parameters:

• sources: Trusted legacy schemas rendered in supplied order; every table must declare tenant_id not explicitly nullable.

Returns: SQL text with a generated timestamp and CREATE TABLE statements; no VPD policies or default clauses are emitted by this converter.

Remarks

Applying SQL and enforcing Oracle tenant isolation remain host responsibilities.

Errors and rejections

For canonical x-db/$defs schemas or missing/nullable tenant_id columns.

Example:

import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
const aggregator = new MigrationAggregator([]);
console.log(aggregator.generateOracle([]));

Example

import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
const aggregator = new MigrationAggregator([]);
console.log(aggregator.generatePostgres([]));

[INTERFACE] OutboxItem

Local mutation and rollback snapshot awaiting upstream synchronization.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

interface OutboxItem {
    id: string;
    tableName: string;
    recordId: string;
    operation: 'INSERT' | 'UPDATE' | 'DELETE';
    payload: Record<string, any>;
    previousState?: Record<string, any> | null;
    status: SyncStatus;
    errorMessage?: string;
    retryCount: number;
    createdAt: string;
}

Parameters

Name	Type	Required	Description
id	string	Yes	Outbox row identifier.
tableName	string	Yes	Target local/upstream table.
recordId	string	Yes	Mutation record identifier.
operation	'INSERT' | 'UPDATE' | 'DELETE'	Yes	INSERT, UPDATE, or DELETE operation forwarded upstream.
payload	Record<string, any>	Yes	Mutation data; update retains only the supplied changes.
previousState	Record<string, any> | null	No	Optional pre-mutation row used for rollback; null for inserts or missing snapshots.
status	SyncStatus	Yes	Persisted synchronization state.
errorMessage	string	No	Optional most recent persisted error description.
retryCount	number	Yes	Number of recognized transient failures recorded so far.
createdAt	string	Yes	ISO creation timestamp used for batch ordering.

Returns

Type declaration; no runtime value.

See also

LocalFirstSqliteAdapter.processOutbox.

Public members

id

Outbox row identifier.

tableName

Target local/upstream table.

recordId

Mutation record identifier.

operation

INSERT, UPDATE, or DELETE operation forwarded upstream.

payload

Mutation data; update retains only the supplied changes.

previousState

Optional pre-mutation row used for rollback; null for inserts or missing snapshots.

status

Persisted synchronization state.

errorMessage

Optional most recent persisted error description.

retryCount

Number of recognized transient failures recorded so far.

createdAt

ISO creation timestamp used for batch ordering.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] PluginMigration

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface PluginMigration {
    id: string;
    scope: 'database' | 'tenant';
    sql: Partial<Record<'sqlite' | 'oracle' | 'postgres', string[]>>;
}

Parameters

Name	Type	Required	Description
id	string	Yes	See the upstream owning declaration.
scope	'database' | 'tenant'	Yes	See the upstream owning declaration.
sql	Partial<Record<'sqlite' | 'oracle' | 'postgres', string[]>>	Yes	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] resolveDataContracts

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

declare function resolveDataContracts(available: readonly DataContract[], requirements: Record<string, string>): DataContractCatalog;

Parameters

Name	Type	Required	Description
available	readonly DataContract[]	Yes	See the upstream owning declaration.
requirements	Record<string, string>	Yes	See the upstream owning declaration.

Returns

DataContractCatalog

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] SchemaMigrationSource

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface SchemaMigrationSource {
    migrations: PluginMigration[];
    schemaDependencies?: Record<string, string>;
    schemaContracts?: DataContract[];
}

Parameters

Name	Type	Required	Description
migrations	PluginMigration[]	Yes	See the upstream owning declaration.
schemaDependencies	Record<string, string>	No	See the upstream owning declaration.
schemaContracts	DataContract[]	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] SchemaSource

Legacy table-schema input collected for migration text generation.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/migration, @alneas/eaos-server/db/migration/aggregator.

Signature

interface SchemaSource {
    pluginId: string;
    pluginName?: string;
    extensionId?: string;
    migrationOrder?: number;
    schemaJson: Record<string, any>;
}

Parameters

Name	Type	Required	Description
pluginId	string	Yes	Plugin ID, or data:{contractId} for resolved data contracts.
pluginName	string	No	Optional display label used in generated SQL comments.
extensionId	string	No	Optional extension ID appended to the source identifier.
migrationOrder	number	No	Sort order from the plugin manifest; defaults to 999 for plugin schemas.
schemaJson	Record<string, any>	Yes	Legacy tables/columns schema; canonical x-db/$defs schemas require reviewed lifecycle migrations instead.

Returns

Type declaration; no runtime value.

See also

MigrationAggregator for a complete usage example.

Public members

pluginId

Plugin ID, or data:{contractId} for resolved data contracts.

pluginName

Optional display label used in generated SQL comments.

extensionId

Optional extension ID appended to the source identifier.

migrationOrder

Sort order from the plugin manifest; defaults to 999 for plugin schemas.

schemaJson

Legacy tables/columns schema; canonical x-db/$defs schemas require reviewed lifecycle migrations instead.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] SqliteDriver

Host SQLite operations required by LocalFirstSqliteAdapter; execution and transaction ownership belong to the host.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

interface SqliteDriver {
    execute(sql: string, params?: any[]): Promise<any>;
    select<T = any>(sql: string, params?: any[]): Promise<T[]>;
}

Parameters

Name	Type	Required	Description
execute	Promise<any>	Yes	Executes SQLite SQL with positional bindings.
select	Promise<T[]>	Yes	Selects SQLite rows using positional bindings.

Returns

Type declaration; no runtime value.

Public members

execute

Executes SQLite SQL with positional bindings.

Parameters:

• sql: SQL statement, including transaction control statements.
• params: Positional values for question-mark placeholders; omitted for parameterless SQL.

Returns: Driver-specific execution result, which the adapter does not inspect.

Errors and rejections

Rejects on driver/database failure; callers determine rollback handling.

Example:

import type { SqliteDriver } from "@alneas/eaos-server/db";
export async function inspectConnectedSqlite(driver: SqliteDriver) {
  // The host opens and closes the connection; this statement changes no records.
  return await driver.execute("SELECT 1 AS ready", []);
}

select

Selects SQLite rows using positional bindings.

Parameters:

• sql: SELECT statement.
• params: Positional values, or omitted for parameterless queries.

Returns: Matching rows, or an empty array.

Type parameters

• T: Row shape expected by the caller; the driver does not establish runtime validation.

Errors and rejections

Rejects on driver/database failure.

Example:

import type { SqliteDriver } from "@alneas/eaos-server/db";
export async function selectConnectedSqlite(driver: SqliteDriver) {
  const rows = await driver.select<{ ready: number }>("SELECT 1 AS ready", []);
  return rows[0]?.ready; // The type argument does not perform runtime validation.
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] SyncErrorEvent

Permanent synchronization failure notification emitted after local rollback handling.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

interface SyncErrorEvent {
    item: OutboxItem;
    error: Error;
    rolledBack: boolean;
}

Parameters

Name	Type	Required	Description
item	OutboxItem	Yes	Outbox item whose permanent failure caused rollback handling.
error	Error	Yes	Underlying synchronization failure.
rolledBack	boolean	Yes	True when rollback handling reached the callback; it is not a remote rollback guarantee.

Returns

Type declaration; no runtime value.

See also

LocalFirstSqliteAdapterOptions.onSyncError.

Public members

item

Outbox item whose permanent failure caused rollback handling.

error

Underlying synchronization failure.

rolledBack

True when rollback handling reached the callback; it is not a remote rollback guarantee.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[TYPE] SyncStatus

Local outbox lifecycle status; successfully synchronized rows are removed by processOutbox.

Imports: @alneas/eaos-server/db, @alneas/eaos-server/db/local-first-sqlite-adapter.

Signature

type SyncStatus = 'pending' | 'syncing' | 'synced' | 'failed';

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Type declaration; no runtime value.

See also

LocalFirstSqliteAdapter.processOutbox.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] TenantSessionContext

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-server/db.

Signature

interface TenantSessionContext {
    tenantId: string;
    userId?: string;
}

Parameters

Name	Type	Required	Description
tenantId	string	Yes	See the upstream owning declaration.
userId	string	No	See the upstream owning declaration.

Returns

Type declaration; no runtime value.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.