@korajs/core 0.6.0 → 1.0.0-beta.1

package/dist/{events-D-FWfFg8.d.ts → events-CqDkr1LN.d.ts}

@@ -89,6 +89,56 @@ declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req exte
     merge(strategy: FieldMergeStrategy): ArrayFieldBuilder<ItemKind, Req, Auto>;
     _build(): FieldDescriptor;
 }
+/**
+ * Field builder for structured object fields with a nested field schema.
+ *
+ * Each nested key merges by its own declared kind (scalars via LWW, nested
+ * arrays via add-wins, nested objects recursively), so two devices editing
+ * different keys of the same object offline both converge on reconnect instead
+ * of one clobbering the other.
+ */
+declare class ObjectFieldBuilder<Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'object', Req, Auto> {
+    private readonly _fields;
+    constructor(fields: Record<string, FieldBuilder>, required?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    optional(): ObjectFieldBuilder<false, Auto>;
+    default(value: Record<string, unknown>): ObjectFieldBuilder<false, Auto>;
+    auto(): ObjectFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): ObjectFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for dynamic-key JSON values. Carries a compile-time shape `T`
+ * for inference while merging structurally as a convergent CRDT: a plain-object
+ * value recurses as a map, an array merges add-wins, any other value is a scalar
+ * leaf under last-write-wins.
+ */
+declare class JsonFieldBuilder<T = unknown, Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'json', Req, Auto> {
+    optional(): JsonFieldBuilder<T, false, Auto>;
+    default(value: T): JsonFieldBuilder<T, false, Auto>;
+    auto(): JsonFieldBuilder<T, false, true>;
+    merge(strategy: FieldMergeStrategy): JsonFieldBuilder<T, Req, Auto>;
+    _build(): FieldDescriptor;
+}
+/**
+ * Field builder for secret fields (passwords, tokens, API keys).
+ *
+ * A secret field's value is never exposed in merge traces, DevTools, or logs
+ * (it is redacted at the point traces are built). Its at-rest protection is
+ * chosen with `.hashed()` (one-way, for passwords) or `.encrypted()` (reversible,
+ * for tokens); the default is `encrypted`.
+ */
+declare class SecretFieldBuilder<Req extends boolean = true, Auto extends boolean = false> extends FieldBuilder<'secret', Req, Auto> {
+    private readonly _secretMode;
+    constructor(secretMode?: SecretMode, required?: Req, defaultValue?: unknown, auto?: Auto, mergeStrategy?: FieldMergeStrategy | null);
+    /** Store this secret as a one-way salted hash (passwords: verify, never read back). */
+    hashed(): SecretFieldBuilder<Req, Auto>;
+    /** Store this secret as reversible ciphertext (tokens/keys: decrypt to use). */
+    encrypted(): SecretFieldBuilder<Req, Auto>;
+    optional(): SecretFieldBuilder<false, Auto>;
+    auto(): SecretFieldBuilder<false, true>;
+    merge(strategy: FieldMergeStrategy): SecretFieldBuilder<Req, Auto>;
+    _build(): FieldDescriptor;
+}
 /**
  * Type builder namespace. The developer's primary interface for defining field types.
  *
@@ -103,6 +153,8 @@ declare class ArrayFieldBuilder<ItemKind extends FieldKind = FieldKind, Req exte
  *   notes: t.richtext(),
  *   tags: t.array(t.string()).default([]),
  *   priority: t.enum(['low', 'medium', 'high']).default('medium'),
+ *   settings: t.object({ theme: t.string(), fontSize: t.number() }),
+ *   metadata: t.json<{ source: string }>(),
  *   createdAt: t.timestamp().auto(),
  * }
  * ```
@@ -115,6 +167,10 @@ declare const t: {
     richtext(): FieldBuilder<"richtext", true, false>;
     enum<const V extends readonly string[]>(values: V): EnumFieldBuilder<V, true, false>;
     array<K extends FieldKind>(itemBuilder: FieldBuilder<K>): ArrayFieldBuilder<K, true, false>;
+    object(fields: Record<string, FieldBuilder>): ObjectFieldBuilder<true, false>;
+    json<T = unknown>(): JsonFieldBuilder<T, true, false>;
+    blob(): FieldBuilder<"blob", true, false>;
+    secret(): SecretFieldBuilder<true, false>;
 };
 
 /**
@@ -390,7 +446,39 @@ interface OperationInput {
 /** Version vector: maps nodeId to the max sequence number seen from that node */
 type VersionVector = Map<string, number>;
 /** Field kinds supported by the schema system */
-type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array';
+type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'enum' | 'array' | 'object' | 'json' | 'blob' | 'secret';
+/**
+ * How a `secret` field's value is protected at rest.
+ * - `hashed`: one-way (passwords). Stored as a salted hash; never read back.
+ * - `encrypted`: reversible (tokens, keys). Stored as ciphertext; decrypted to use.
+ */
+type SecretMode = 'hashed' | 'encrypted';
+/**
+ * A content-addressed reference to binary data stored out of band.
+ *
+ * A `blob` field never carries the bytes in the operation log; it carries this
+ * small reference. The bytes live in a content-addressed blob store, keyed by
+ * `hash`, so identical content is stored once and never re-synced to a peer that
+ * already has that hash.
+ */
+interface BlobRef {
+    /** Hex-encoded SHA-256 hash of the bytes. The content address. */
+    hash: string;
+    /** Size of the bytes in bytes. */
+    size: number;
+    /** Optional MIME type (for example "image/png"). */
+    mimeType?: string;
+    /** Optional original filename. */
+    filename?: string;
+    /**
+     * Hex-encoded SHA-256 hash of this blob's manifest — the small chunk index a
+     * peer fetches first to learn how to pull the bytes out of band. Present when
+     * the blob was stored for transfer; absent for a bare reference created without
+     * chunking. Because it is a content address like `hash`, the manifest is fetched
+     * and integrity-verified over the same channel as the chunks.
+     */
+    manifestHash?: string;
+}
 /**
  * Comprehensive sync diagnostics snapshot.
  * Provides connection, latency, throughput, queue, and error metrics
@@ -398,7 +486,7 @@ type FieldKind = 'string' | 'number' | 'boolean' | 'timestamp' | 'richtext' | 'e
  */
 interface SyncDiagnosticsSnapshot {
     /** Current developer-facing sync status */
-    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch';
+    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch' | 'clock-error';
     /** Timestamp when the current connection was established, or null if disconnected */
     connectedAt: number | null;
     /** Timestamp when the last disconnection occurred, or null if never disconnected */
@@ -490,6 +578,17 @@ interface FieldDescriptor {
     mergeStrategy: FieldMergeStrategy | null;
     /** State machine transition map for enum fields. Null if no transitions declared. */
     transitions: TransitionMap | null;
+    /**
+     * Nested field descriptors for `object` fields (each key merges by its own
+     * kind). Null for `json` fields (dynamic keys, resolved structurally) and for
+     * all non-structured kinds.
+     */
+    nestedFields?: Record<string, FieldDescriptor> | null;
+    /**
+     * At-rest protection mode for `secret` fields (`hashed` or `encrypted`).
+     * Null/absent for every other kind.
+     */
+    secretMode?: SecretMode | null;
 }
 /**
  * Defines a state machine on an enum field, constraining valid state transitions.
@@ -696,6 +795,18 @@ type KoraEvent = {
 } | {
     type: 'sync:auth-failed';
     reason: string;
+} | {
+    type: 'sync:clock-skew';
+    /** serverTime - localTime in ms. Negative = this device's clock is fast. */
+    skewMs: number;
+    severity: 'info' | 'slow-warning' | 'fast-blocked';
+    source: 'handshake' | 'server-reject';
+} | {
+    type: 'sync:clock-rebase';
+    /** Number of unsynced operations that were re-stamped. */
+    rebasedCount: number;
+    /** How far ahead of server time the most future queued operation was, in ms. */
+    maxSkewMs: number;
 } | {
     type: 'sync:sent';
     operations: Operation[];
@@ -793,4 +904,4 @@ interface KoraEventEmitter {
     emit<T extends KoraEventType>(event: KoraEventByType<T>): void;
 }
 
-export { type AtomicOpType as A, type SequenceConfig as B, type CustomResolver as C, type StateMachineDefinition as D, EnumFieldBuilder as E, FieldBuilder as F, type SyncDiagnosticsSnapshot as G, type HLCTimestamp as H, type SyncRuleDefinition as I, type TimeSource as J, type KoraEvent as K, migrate as L, type MigrationDefinition as M, t as N, type OperationType as O, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, type VersionVector as V, type AtomicOp as a, type CollectionDefinition as b, type RelationDefinition as c, ArrayFieldBuilder as d, type FieldKind as e, type Operation as f, type MigrationStep as g, type StateMachineConstraint as h, type TransitionValidationResult as i, CONNECTION_QUALITIES as j, type ConnectionQuality as k, type Constraint as l, type FieldDescriptor as m, type FieldMergeStrategy as n, type KoraEventByType as o, type KoraEventEmitter as p, type KoraEventListener as q, type KoraEventType as r, MERGE_STRATEGIES as s, type MergeStrategy as t, type MergeTrace as u, MigrationBuilder as v, type OnDeleteAction as w, type OperationInput as x, type RelationType as y, RollbackBuilder as z };
+export { type AtomicOpType as A, type BlobRef as B, type CollectionDefinition as C, type SecretMode as D, EnumFieldBuilder as E, FieldBuilder as F, type SequenceConfig as G, type HLCTimestamp as H, type StateMachineDefinition as I, JsonFieldBuilder as J, type KoraEvent as K, type SyncDiagnosticsSnapshot as L, type MigrationDefinition as M, type SyncRuleDefinition as N, type OperationType as O, type TimeSource as P, migrate as Q, type RandomSource as R, type SchemaDefinition as S, type TransitionMap as T, t as U, type VersionVector as V, type AtomicOp as a, type CustomResolver as b, type RelationDefinition as c, ArrayFieldBuilder as d, type FieldKind as e, type Operation as f, type MigrationStep as g, type StateMachineConstraint as h, type TransitionValidationResult as i, CONNECTION_QUALITIES as j, type ConnectionQuality as k, type Constraint as l, type FieldDescriptor as m, type FieldMergeStrategy as n, type KoraEventByType as o, type KoraEventEmitter as p, type KoraEventListener as q, type KoraEventType as r, MERGE_STRATEGIES as s, type MergeStrategy as t, type MergeTrace as u, MigrationBuilder as v, type OnDeleteAction as w, type OperationInput as x, type RelationType as y, RollbackBuilder as z };