@korajs/core 1.0.0-beta.12 → 1.0.0-beta.13

package/README.md

@@ -1,13 +1,13 @@
 # @korajs/core
 
-Schema definitions, operations, Hybrid Logical Clock, version vectors, and type inference for Kora.js. This is the foundation package -- all other packages depend on it.
+Schema definitions, type inference, operations, the hybrid logical clock, version vectors and the record fold (the per-field merge every replica runs) for Kora.js. It is the foundation: every other package depends on it.
 
 > Most developers don't install this directly. Use [`korajs`](https://www.npmjs.com/package/korajs) instead.
 
 ## Install
 
 ```bash
-pnpm add @korajs/core
+pnpm add @korajs/core@beta
 ```
 
 ## Usage
@@ -25,7 +25,7 @@ const schema = defineSchema({
         title: t.string(),
         completed: t.boolean().default(false),
         tags: t.array(t.string()).default([]),
-        notes: t.richtext(),
+        notes: t.richtext().optional(),
         priority: t.enum(['low', 'medium', 'high']).default('medium'),
         createdAt: t.timestamp().auto(),
       },
@@ -48,29 +48,37 @@ const ts2 = clock.now()
 // Timestamps are always monotonically increasing
 HybridLogicalClock.compare(ts1, ts2) // negative (ts1 < ts2)
 
-// Merge with a remote timestamp
-const ts3 = clock.receive(remoteTimestamp)
+// Merge a remote timestamp (rejected, without changing the clock, if malformed or
+// more than 5 minutes in the future)
+const ts3 = clock.receive({ wallTime: ts2.wallTime + 5, logical: 0, nodeId: 'node-2' })
 ```
 
 ### Version Vectors
 
 ```typescript
-import { mergeVectors, deltaOperations } from '@korajs/core'
+import { computeDelta, mergeVectors, type Operation, type VersionVector } from '@korajs/core'
+
+declare const localVector: VersionVector
+declare const remoteVector: VersionVector
+declare const log: { getRange(nodeId: string, from: number, to: number): Promise<Operation[]> }
 
 const merged = mergeVectors(localVector, remoteVector)
-const missing = deltaOperations(localVector, remoteVector, operationLog)
+const missing = await computeDelta(localVector, remoteVector, log) // causal order
 ```
 
 ## What's Inside
 
-- **Schema system** -- `defineSchema`, `t` field builders, full TypeScript type inference
-- **Operation type** -- immutable, content-addressed mutation records
-- **Hybrid Logical Clock** -- causal ordering without synchronized clocks
-- **Version vectors** -- efficient delta sync computation
-- **Error types** -- structured `KoraError` base class
+- **Schema system**: `defineSchema`, `t` field builders, full TypeScript type inference
+- **Operation type**: immutable, content-addressed mutation records
+- **Hybrid Logical Clock**: causal ordering without synchronized clocks
+- **Version vectors**: delta computation for uploads
+- **Record fold**: `foldRecord`, `mergeOp`, `materialize`, `joinStates`: one deterministic per-field CRDT
+- **Atomic ops**: `op.increment`, `op.append` and friends
+- **Migrations**: `migrate()` builders for schema versions
+- **Error types**: structured `KoraError` base class with codes
 
 ## License
 
 MIT
 
-See the [full documentation](https://github.com/ehoneahobed/kora) for guides, API reference, and examples.
+See the [Core API reference](https://korajs.dev/api/core) and the [guides](https://korajs.dev).

package/dist/bindings/index.d.cts

@@ -1,9 +1,9 @@
-import { p as KoraEventEmitter } from '../events-D7JCtQSD.cjs';
-import { S as ScopeMap } from '../build-scope-map-CItP1gsz.cjs';
+import { X as KoraEventEmitter } from '../events-BSU-0z5O.cjs';
+import { S as ScopeMap } from '../build-scope-map-ClIq_doj.cjs';
 
 /** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
 interface KoraBindingSyncStatus {
-    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required' | 'encryption-locked';
     reconnecting: boolean;
     pendingOperations: number;
     lastSyncedAt: number | null;
@@ -62,8 +62,14 @@ interface UseMutationResultBase<TData, TArgs extends unknown[]> {
  * Created by `createKoraAuthSync()` in `@korajs/auth`.
  */
 interface AuthSyncBinding {
-    /** Returns the access token for sync handshake (empty string when signed out). */
-    auth: () => Promise<{
+    /**
+     * Returns the access token for sync handshake (empty string when signed out).
+     * Called with `{ forceRefresh: true }` after the server ended the session with
+     * `AUTH_EXPIRED` / `AUTH_REVOKED`: refresh instead of returning the cached token.
+     */
+    auth: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<{
         token: string;
     }>;
     /** Resolve whether sync may currently open a transport. Tokens are never used as readiness signals. */
@@ -92,7 +98,21 @@ type AuthSyncState = {
 } | {
     state: 'authenticated';
     userId: string;
-    token: string;
+    /**
+     * Fresh access token, or null while authenticated-offline: the identity
+     * is known from stored credentials but no fresh token can be minted now.
+     * The local store opens either way; a sync transport waits for a token.
+     */
+    token: string | null;
+    /** Device id of the stored credentials, when known. */
+    deviceId?: string;
+    /** True while the session is authenticated-offline (or locked). */
+    offline?: boolean;
+    /**
+     * True when the offline grace period ran out or the device clock moved
+     * backwards. The UI should lock; local data is never wiped.
+     */
+    locked?: boolean;
 };
 
 interface MutationControllerState {

package/dist/bindings/index.d.ts

@@ -1,9 +1,9 @@
-import { p as KoraEventEmitter } from '../events-D7JCtQSD.js';
-import { S as ScopeMap } from '../build-scope-map-Cv5HfCQP.js';
+import { X as KoraEventEmitter } from '../events-BSU-0z5O.js';
+import { S as ScopeMap } from '../build-scope-map-CIFa58oA.js';
 
 /** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
 interface KoraBindingSyncStatus {
-    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required';
+    status: 'connected' | 'reconnecting' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error' | 'auth-required' | 'encryption-locked';
     reconnecting: boolean;
     pendingOperations: number;
     lastSyncedAt: number | null;
@@ -62,8 +62,14 @@ interface UseMutationResultBase<TData, TArgs extends unknown[]> {
  * Created by `createKoraAuthSync()` in `@korajs/auth`.
  */
 interface AuthSyncBinding {
-    /** Returns the access token for sync handshake (empty string when signed out). */
-    auth: () => Promise<{
+    /**
+     * Returns the access token for sync handshake (empty string when signed out).
+     * Called with `{ forceRefresh: true }` after the server ended the session with
+     * `AUTH_EXPIRED` / `AUTH_REVOKED`: refresh instead of returning the cached token.
+     */
+    auth: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<{
         token: string;
     }>;
     /** Resolve whether sync may currently open a transport. Tokens are never used as readiness signals. */
@@ -92,7 +98,21 @@ type AuthSyncState = {
 } | {
     state: 'authenticated';
     userId: string;
-    token: string;
+    /**
+     * Fresh access token, or null while authenticated-offline: the identity
+     * is known from stored credentials but no fresh token can be minted now.
+     * The local store opens either way; a sync transport waits for a token.
+     */
+    token: string | null;
+    /** Device id of the stored credentials, when known. */
+    deviceId?: string;
+    /** True while the session is authenticated-offline (or locked). */
+    offline?: boolean;
+    /**
+     * True when the offline grace period ran out or the device clock moved
+     * backwards. The UI should lock; local data is never wiped.
+     */
+    locked?: boolean;
 };
 
 interface MutationControllerState {

package/dist/{build-scope-map-Cv5HfCQP.d.ts → build-scope-map-CIFa58oA.d.ts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './events-D7JCtQSD.js';
+import { S as SchemaDefinition } from './events-BSU-0z5O.js';
 
 /**
  * Per-collection scope map: `{ collectionName: { field: value, ... } }`

package/dist/{build-scope-map-CItP1gsz.d.cts → build-scope-map-ClIq_doj.d.cts}

@@ -1,4 +1,4 @@
-import { S as SchemaDefinition } from './events-D7JCtQSD.cjs';
+import { S as SchemaDefinition } from './events-BSU-0z5O.cjs';
 
 /**
  * Per-collection scope map: `{ collectionName: { field: value, ... } }`