@sovereignbase/convergent-replicated-struct 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -2,182 +2,153 @@
 /**
  * Represents the internal replicated state for a single field.
  */
-type OOStructStateEntry<V> = {
+type CRStructStateEntry<V> = {
     /**
      * The identifier of the current winning value.
      */
-    __uuidv7: string;
+    uuidv7: string;
     /**
      * The current winning value.
      */
-    __value: V;
+    value: V;
     /**
      * The predecessor identifier for the current winning value.
      */
-    __after: string;
+    predecessor: string;
     /**
      * Identifiers known to have been overwritten for the field.
      */
-    __overwrites: Set<string>;
+    tombstones: Set<string>;
 };
 /**
  * Represents the internal replicated state of an OO-Struct replica.
  */
-type OOStructState<T extends Record<string, unknown>> = {
-    [K in keyof T]: OOStructStateEntry<T[K]>;
+type CRStructState<T extends Record<string, unknown>> = {
+    entries: {
+        [K in keyof T]: CRStructStateEntry<T[K]>;
+    };
+    defaults: T;
 };
 /**Serlialized projection of replica state*/
 /**
  * Represents the serialized state for a single field.
  */
-type OOStructSnapshotEntry<V> = {
+type CRStructSnapshotEntry<V> = {
     /**
      * The identifier of the current winning value.
      */
-    __uuidv7: string;
+    uuidv7: string;
     /**
      * The serialized current winning value.
      */
-    __value: V;
+    value: V;
     /**
      * The predecessor identifier for the current winning value.
      */
-    __after: string;
+    predecessor: string;
     /**
      * Serialized overwritten identifiers for the field.
      */
-    __overwrites: Array<string>;
+    tombstones: Array<string>;
 };
 /**
  * Represents a serialized snapshot of the full replica state.
  */
-type OOStructSnapshot<T extends Record<string, unknown>> = {
-    [K in keyof T]: OOStructSnapshotEntry<T[K]>;
+type CRStructSnapshot<T extends Record<string, unknown>> = {
+    [K in keyof T]: CRStructSnapshotEntry<T[K]>;
 };
 /**Resolved projection of replica state*/
 /**
  * Represents visible field values that changed during a local operation or merge.
  */
-type OOStructChange<T extends Record<string, unknown>> = Partial<T>;
+type CRStructChange<T extends Record<string, unknown>> = Partial<T>;
 /**(T)*/
-/**A "report" on what the replica has seen*/
-/**
- * Represents the acknowledgement frontier for a set of field keys.
- */
-type OOStructAcknowledgementFrontier<K extends string> = Record<K, string>;
 /**Partial changes to gossip*/
 /**
  * Represents a partial serialized state projection exchanged between replicas.
  */
-type OOStructDelta<T extends Record<string, unknown>> = Partial<OOStructSnapshot<T>>;
+type CRStructDelta<T extends Record<string, unknown>> = Partial<CRStructSnapshot<T>>;
+/**A "report" on what the replica has seen*/
 /**
  * Represents the current acknowledgement frontier emitted by a replica.
  */
-type OOStructAck<T extends Record<string, unknown>> = Partial<OOStructAcknowledgementFrontier<Extract<keyof T, string>>>;
+type CRStructAck<T extends Record<string, unknown>> = Partial<Record<keyof T, string>>;
 /***/
 /**
  * Maps OO-Struct event names to their event payload shapes.
  */
-type OOStructEventMap<T extends Record<string, unknown>> = {
+type CRStructEventMap<T extends Record<string, unknown>> = {
     /** STATE / PROJECTION */
-    snapshot: OOStructSnapshot<T>;
-    change: OOStructChange<T>;
+    snapshot: CRStructSnapshot<T>;
+    change: CRStructChange<T>;
     /** GOSSIP / PROTOCOL */
-    delta: OOStructDelta<T>;
-    ack: OOStructAck<T>;
+    delta: CRStructDelta<T>;
+    ack: CRStructAck<T>;
 };
 /**
  * Represents a strongly typed OO-Struct event listener.
  */
-type OOStructEventListener<T extends Record<string, unknown>, K extends keyof OOStructEventMap<T>> = ((event: CustomEvent<OOStructEventMap<T>[K]>) => void) | {
-    handleEvent(event: CustomEvent<OOStructEventMap<T>[K]>): void;
+type CRStructEventListener<T extends Record<string, unknown>, K extends keyof CRStructEventMap<T>> = ((event: CustomEvent<CRStructEventMap<T>[K]>) => void) | {
+    handleEvent(event: CustomEvent<CRStructEventMap<T>[K]>): void;
 };
 /**
  * Resolves an event name to its corresponding listener type.
  */
-type OOStructEventListenerFor<T extends Record<string, unknown>, K extends string> = K extends keyof OOStructEventMap<T> ? OOStructEventListener<T, K> : EventListenerOrEventListenerObject;
+type CRStructEventListenerFor<T extends Record<string, unknown>, K extends string> = K extends keyof CRStructEventMap<T> ? CRStructEventListener<T, K> : EventListenerOrEventListenerObject;
 
 /**
- * Represents an observed-overwrite struct replica.
- *
- * The struct shape is fixed by the provided default values.
+ * Runtime implementation for a proxy-backed CR-Struct replica.
  */
-declare class OOStruct<T extends Record<string, unknown>> {
-    private readonly __eventTarget;
-    private readonly __defaults;
-    private readonly __state;
-    private __live;
+declare class CRStructRaw<T extends Record<string, unknown>> {
+    private readonly state;
+    private readonly eventTarget;
     /**
      * Creates a replica from default values and an optional snapshot.
      *
-     * @param defaults - The default field values that define the struct shape.
-     * @param snapshot - An optional serialized snapshot used for hydration.
-     * @throws {OOStructError} Thrown when the default values are not supported by `structuredClone`.
-     */
-    constructor(defaults: {
-        [K in keyof T]: T[K];
-    }, snapshot?: OOStructSnapshot<T>);
-    /**CRUD*/
-    /**
-     * Creates a new replica.
+     * The struct shape is fixed by the provided default values. The returned
+     * proxy exposes those fields as direct properties on the instance.
      *
      * @param defaults - The default field values that define the struct shape.
-     * @param snapshot - An optional serialized snapshot used for hydration.
-     * @returns A new OO-Struct replica.
-     */
-    static create<T extends Record<string, unknown>>(defaults: {
-        [K in keyof T]: T[K];
-    }, snapshot?: OOStructSnapshot<T>): OOStruct<T>;
-    /**
-     * Reads the current value of a field.
-     *
-     * @param key - The field key to read.
-     * @returns A cloned copy of the field's current value.
-     */
-    read<K extends keyof T>(key: K): T[K];
-    /**
-     * Overwrites a field with a new value.
-     *
-     * @param key - The field key to overwrite.
-     * @param value - The next value for the field.
-     * @throws {OOStructError} Thrown when the value is not supported by `structuredClone`.
-     * @throws {OOStructError} Thrown when the value runtime type does not match the default value runtime type.
+     * @param snapshot - An optional serialized snapshot used to hydrate the replica.
+     * @throws {CRStructError} Thrown when the default values are not supported by `structuredClone`.
      */
-    update<K extends keyof T>(key: K, value: T[K]): void;
+    constructor(defaults: T, snapshot?: CRStructSnapshot<T>);
     /**
-     * Resets one field or the entire struct back to default values.
+     * Applies a remote or local delta to the replica state.
      *
-     * @param key - The optional field key to reset. When omitted, every field is reset.
+     * @param crStructDelta - The partial serialized field state to merge.
      */
-    delete<K extends keyof T>(key?: K): void;
-    /**MAGS*/
-    /**
-     * Merges an incoming delta into the current replica.
-     *
-     * @param replica - The incoming partial snapshot projection to merge.
-     */
-    merge<K extends keyof T>(replica: OOStructDelta<T>): void;
+    merge(crStructDelta: CRStructDelta<T>): void;
     /**
      * Emits the current acknowledgement frontier for each field.
      */
-    acknowledge<K extends Extract<keyof T, string>>(): void;
+    acknowledge(): void;
     /**
      * Removes overwritten identifiers that every provided frontier has acknowledged.
      *
      * @param frontiers - A collection of acknowledgement frontiers to compact against.
      */
-    garbageCollect<K extends Extract<keyof T, string>>(frontiers: Array<OOStructAck<T>>): void;
+    garbageCollect(frontiers: Array<CRStructAck<T>>): void;
     /**
      * Emits a serialized snapshot of the current replica state.
      */
     snapshot(): void;
-    /**ADDITIONAL*/
     /**
      * Returns the struct field keys.
      *
      * @returns The field keys in the current replica.
      */
     keys<K extends keyof T>(): Array<K>;
+    /**
+     * Resets every field in the replica back to its default value.
+     */
+    clear(): void;
+    /**
+     * Returns a cloned plain object view of the current replica fields.
+     *
+     * @returns The current field values keyed by field name.
+     */
+    clone(): T;
     /**
      * Returns cloned copies of the current field values.
      *
@@ -190,7 +161,20 @@ declare class OOStruct<T extends Record<string, unknown>> {
      * @returns The current field entries.
      */
     entries<K extends keyof T>(): Array<[K, T[K]]>;
-    /**EVENTS*/
+    /**
+     * Returns a serializable snapshot representation of this replica.
+     *
+     * Called automatically by `JSON.stringify`.
+     */
+    toJSON(): CRStructSnapshot<T>;
+    /**
+     * Returns this replica as a JSON string.
+     */
+    toString(): string;
+    /**
+     * Iterates over the current live field entries.
+     */
+    [Symbol.iterator](): IterableIterator<[keyof T, T[keyof T]]>;
     /**
      * Registers an event listener.
      *
@@ -198,7 +182,7 @@ declare class OOStruct<T extends Record<string, unknown>> {
      * @param listener - The listener to register.
      * @param options - Listener registration options.
      */
-    addEventListener<K extends keyof OOStructEventMap<T>>(type: K, listener: OOStructEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof CRStructEventMap<T>>(type: K, listener: CRStructEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
     /**
      * Removes an event listener.
      *
@@ -206,21 +190,205 @@ declare class OOStruct<T extends Record<string, unknown>> {
      * @param listener - The listener to remove.
      * @param options - Listener removal options.
      */
-    removeEventListener<K extends keyof OOStructEventMap<T>>(type: K, listener: OOStructEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
-    /**HELPERS*/
-    /**
-     * Overwrites a field and returns the serialized delta entry for that overwrite.
-     *
-     * @param key - The field key to overwrite.
-     * @param value - The next value for the field.
-     * @returns The serialized snapshot entry for the new winning value.
-     */
-    private overwriteAndReturnSnapshotEntry;
+    removeEventListener<K extends keyof CRStructEventMap<T>>(type: K, listener: CRStructEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
 }
+type CRStruct<T extends Record<string, unknown>> = CRStructRaw<T> & T;
+declare const CRStruct: {
+    new <T extends Record<string, unknown>>(defaults: T, snapshot?: CRStructSnapshot<T>): CRStruct<T>;
+};
 
 /**
  * Error codes thrown by {@link OOStruct}.
  */
-type OOStructErrorCode = 'DEFAULTS_NOT_CLONEABLE' | 'VALUE_NOT_CLONEABLE' | 'VALUE_TYPE_MISMATCH';
+type CRStructErrorCode = 'DEFAULTS_NOT_CLONEABLE' | 'VALUE_NOT_CLONEABLE' | 'VALUE_TYPE_MISMATCH';
+
+/**
+ * Creates internal CR-Struct state from default values and an optional snapshot.
+ *
+ * Default values define the replica field set. Compatible snapshot entries are
+ * parsed into live state entries, and invalid snapshot entries are ignored so
+ * the corresponding field falls back to a freshly initialized default-backed
+ * entry.
+ *
+ * @param defaults - Default field values that define the replica shape.
+ * @param snapshot - Optional serialized state used to hydrate matching fields.
+ *
+ * @returns
+ * A hydrated internal CR-Struct state object.
+ *
+ * @throws {CRStructError} Thrown when the default values are not supported by `structuredClone`.
+ *
+ * Time complexity: O(k + c + s + t), worst case O(k + c + s + t)
+ *
+ * k = default field count
+ * c = total cloned payload size across defaults and accepted snapshot values
+ * s = snapshot entries inspected for matching fields
+ * t = tombstone count materialized for accepted snapshot entries
+ *
+ * Space complexity: O(k + c + t)
+ */
+declare function __create<T extends Record<string, unknown>>(defaults: T, snapshot?: CRStructSnapshot<T>): CRStructState<T>;
+
+/**
+ * Reads and clones the current value of a single field.
+ *
+ * @param key - The field key to read.
+ * @param crStructReplica - The replica state that owns the field.
+ *
+ * @returns
+ * A cloned copy of the field's current value.
+ *
+ * Time complexity: O(c), worst case O(c)
+ *
+ * c = cloned field payload size
+ *
+ * Space complexity: O(c)
+ */
+declare function __read<T extends Record<string, unknown>>(key: keyof T, crStructReplica: CRStructState<T>): T[keyof T];
+
+/**
+ * Overwrites a field with a new value and emits the resulting projections.
+ *
+ * The incoming value is cloned first, validated against the default field
+ * runtime type, and then written back as the current winning value for the
+ * target field.
+ *
+ * @param key - The field key to overwrite.
+ * @param value - The next value for the field.
+ * @param crStructReplica - The replica state that owns the field.
+ *
+ * @returns
+ * The visible change projection and serialized delta for the overwrite.
+ *
+ * @throws {CRStructError} Thrown when the value is not supported by `structuredClone`.
+ * @throws {CRStructError} Thrown when the value runtime type does not match the default value runtime type.
+ *
+ * Time complexity: O(c + t), worst case O(c + t)
+ *
+ * c = cloned and serialized payload size for the updated value
+ * t = tombstone count serialized for the target field
+ *
+ * Space complexity: O(c + t)
+ */
+declare function __update<T extends Record<string, unknown>>(key: keyof T, value: T[keyof T], crStructReplica: CRStructState<T>): {
+    change: CRStructChange<T>;
+    delta: CRStructDelta<T>;
+} | false;
+
+/**
+ * Resets one field or the entire struct back to default values.
+ *
+ * Each touched field is overwritten from the replica defaults and contributes a
+ * visible change projection plus a serialized delta describing the reset.
+ *
+ * @param crStructReplica - The replica state to reset.
+ * @param key - The optional field key to reset. When omitted, every field is reset.
+ *
+ * @returns
+ * The visible change projection and serialized delta for the reset, or `false`
+ * when a keyed reset targets a field outside the replica.
+ *
+ * Time complexity: O(k + c + t), worst case O(k + c + t)
+ *
+ * k = number of fields being reset
+ * c = cloned and serialized payload size across reset field values
+ * t = tombstone count serialized across reset fields
+ *
+ * Space complexity: O(k + c + t)
+ */
+declare function __delete<T extends Record<string, unknown>>(crStructReplica: CRStructState<T>, key?: keyof T): {
+    change: CRStructChange<T>;
+    delta: CRStructDelta<T>;
+} | false;
+
+/**
+ * Merges an incoming delta into the current replica.
+ *
+ * Unknown fields and invalid snapshot entries are ignored. Accepted candidates
+ * extend local tombstone knowledge, may advance the current winning value, and
+ * may emit a return delta when the local state already dominates the incoming
+ * entry.
+ *
+ * @param crStructDelta - The incoming partial snapshot projection to merge.
+ * @param crStructReplica - The local replica state to merge into.
+ *
+ * @returns
+ * The visible change projection and reply delta, or `false` when the input is
+ * invalid or produces no outbound effect.
+ *
+ * Time complexity: O(d + l + i + c), worst case O(d + l + i + c)
+ *
+ * d = incoming delta field count
+ * l = local tombstone count processed across touched fields
+ * i = incoming tombstone count processed across accepted delta entries
+ * c = cloned and serialized payload size across emitted changes and reply deltas
+ *
+ * Space complexity: O(d + l + c)
+ */
+declare function __merge<T extends Record<string, unknown>>(crStructDelta: CRStructDelta<T>, crStructReplica: CRStructState<T>): {
+    change: CRStructChange<T>;
+    delta: CRStructDelta<T>;
+} | false;
+
+/**
+ * Emits the current acknowledgement frontier for each field.
+ *
+ * Each field reports the largest tombstone identifier currently known for that
+ * field.
+ *
+ * @param crStructReplica - The replica state to summarize.
+ *
+ * @returns
+ * An acknowledgement frontier keyed by field name.
+ *
+ * Time complexity: O(k + t), worst case O(k + t)
+ *
+ * k = replica field count
+ * t = total tombstone count across all fields
+ *
+ * Space complexity: O(k)
+ */
+declare function __acknowledge<T extends Record<string, unknown>>(crStructReplica: CRStructState<T>): CRStructAck<T> | false;
+
+/**
+ * Removes overwritten identifiers that every provided frontier has acknowledged.
+ *
+ * The smallest valid acknowledgement per field is collected first, then local
+ * tombstones at or below that frontier are removed while keeping the current
+ * predecessor identifier intact.
+ *
+ * @param frontiers - A collection of acknowledgement frontiers to compact against.
+ * @param crStructReplica - The replica state to compact.
+ *
+ * Time complexity: O(a + t), worst case O(a + t)
+ *
+ * a = acknowledgement entries scanned across all provided frontiers
+ * t = tombstone count scanned across compacted fields
+ *
+ * Space complexity: O(k)
+ *
+ * k = fields that receive a valid acknowledgement frontier
+ */
+declare function __garbageCollect<T extends Record<string, unknown>>(frontiers: Array<CRStructAck<T>>, crStructReplica: CRStructState<T>): void;
+
+/**
+ * Serializes the current replica state into a snapshot projection.
+ *
+ * Each processed state entry is converted into its serializable snapshot form.
+ *
+ * @param crStructReplica - The replica state to serialize.
+ *
+ * @returns
+ * A serializable snapshot projection of the replica state.
+ *
+ * Time complexity: O(k + t + c), worst case O(k + t + c)
+ *
+ * k = state entry count processed by the serializer
+ * t = tombstone count serialized across processed entries
+ * c = serialized payload size across processed values
+ *
+ * Space complexity: O(k + t + c)
+ */
+declare function __snapshot<T extends Record<string, unknown>>(crStructReplica: CRStructState<T>): CRStructSnapshot<T>;
 
-export { OOStruct, type OOStructAck, type OOStructAcknowledgementFrontier, type OOStructChange, type OOStructDelta, type OOStructErrorCode, type OOStructEventListener, type OOStructEventListenerFor, type OOStructEventMap, type OOStructSnapshot, type OOStructSnapshotEntry, type OOStructState, type OOStructStateEntry };
+export { CRStruct, type CRStructAck, type CRStructChange, type CRStructDelta, type CRStructErrorCode, type CRStructEventListener, type CRStructEventListenerFor, type CRStructEventMap, type CRStructSnapshot, type CRStructSnapshotEntry, type CRStructState, type CRStructStateEntry, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };