@topgunbuild/core 0.2.0-alpha → 0.2.1

package/dist/index.d.mts

@@ -403,29 +403,59 @@ declare function hashORMapRecord<V>(record: ORMapRecord<V>): number;
 declare function compareTimestamps(a: Timestamp, b: Timestamp): number;
 
 /**
- * FNV-1a Hash implementation for strings.
- * Fast, non-cryptographic, synchronous.
- * Good enough for data synchronization checks.
+ * Hash utilities for TopGun
+ *
+ * Uses native xxHash64 when available (via @topgunbuild/native),
+ * falls back to FNV-1a for JS-only environments.
+ *
+ * Phase 3.05: Native Hash Integration
+ */
+/**
+ * Hash a string to a 32-bit unsigned integer.
+ *
+ * Uses native xxHash64 (truncated to 32 bits) when available,
+ * otherwise falls back to FNV-1a.
+ *
+ * @param str - String to hash
+ * @returns 32-bit unsigned integer hash
  */
 declare function hashString(str: string): number;
 /**
  * Combines multiple hash numbers into one order-independent hash.
- * Used for combining bucket hashes.
- * XOR is simple and effective for order-independent combination,
- * but for Merkle trees we usually want position dependence if it's a Trie,
- * or order-independence if it's a Set.
- * Here we simply sum or XOR.
+ * Used for combining bucket hashes in Merkle trees.
+ *
+ * Uses simple sum (with overflow handling) for order-independence.
+ *
+ * @param hashes - Array of hash values to combine
+ * @returns Combined hash as 32-bit unsigned integer
  */
 declare function combineHashes(hashes: number[]): number;
+/**
+ * Check if native hash module is being used.
+ * Useful for diagnostics and testing.
+ */
+declare function isUsingNativeHash(): boolean;
+/**
+ * Force use of FNV-1a hash (for testing/compatibility).
+ * After calling this, hashString will always use FNV-1a.
+ */
+declare function disableNativeHash(): void;
+/**
+ * Re-enable native hash loading (for testing).
+ * Resets the load state so native module can be loaded again.
+ */
+declare function resetNativeHash(): void;
 
 /**
  * Serializes a JavaScript object to MessagePack binary format.
+ * Uses msgpackr for 2-5x faster serialization compared to @msgpack/msgpack.
  * @param data The data to serialize.
  * @returns A Uint8Array containing the serialized data.
  */
 declare function serialize(data: unknown): Uint8Array;
 /**
  * Deserializes MessagePack binary data to a JavaScript object.
+ * Uses msgpackr for 2-5x faster deserialization compared to @msgpack/msgpack.
  * @param data The binary data to deserialize (Uint8Array or ArrayBuffer).
  * @returns The deserialized object.
  */
@@ -467,6 +497,17 @@ interface Principal {
     [key: string]: any;
 }
 
+/**
+ * Write Concern schema - defines when an operation is considered acknowledged.
+ */
+declare const WriteConcernSchema: z.ZodEnum<{
+    FIRE_AND_FORGET: "FIRE_AND_FORGET";
+    MEMORY: "MEMORY";
+    APPLIED: "APPLIED";
+    REPLICATED: "REPLICATED";
+    PERSISTED: "PERSISTED";
+}>;
+type WriteConcernValue = z.infer<typeof WriteConcernSchema>;
 declare const TimestampSchema: z.ZodObject<{
     millis: z.ZodNumber;
     counter: z.ZodNumber;
@@ -540,6 +581,14 @@ declare const ClientOpSchema: z.ZodObject<{
         ttlMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
     orTag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    writeConcern: z.ZodOptional<z.ZodEnum<{
+        FIRE_AND_FORGET: "FIRE_AND_FORGET";
+        MEMORY: "MEMORY";
+        APPLIED: "APPLIED";
+        REPLICATED: "REPLICATED";
+        PERSISTED: "PERSISTED";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const AuthMessageSchema: z.ZodObject<{
     type: z.ZodLiteral<"AUTH">;
@@ -595,6 +644,14 @@ declare const ClientOpMessageSchema: z.ZodObject<{
             ttlMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
         orTag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        writeConcern: z.ZodOptional<z.ZodEnum<{
+            FIRE_AND_FORGET: "FIRE_AND_FORGET";
+            MEMORY: "MEMORY";
+            APPLIED: "APPLIED";
+            REPLICATED: "REPLICATED";
+            PERSISTED: "PERSISTED";
+        }>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 declare const OpBatchMessageSchema: z.ZodObject<{
@@ -625,7 +682,23 @@ declare const OpBatchMessageSchema: z.ZodObject<{
                 ttlMs: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>>;
             orTag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            writeConcern: z.ZodOptional<z.ZodEnum<{
+                FIRE_AND_FORGET: "FIRE_AND_FORGET";
+                MEMORY: "MEMORY";
+                APPLIED: "APPLIED";
+                REPLICATED: "REPLICATED";
+                PERSISTED: "PERSISTED";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        writeConcern: z.ZodOptional<z.ZodEnum<{
+            FIRE_AND_FORGET: "FIRE_AND_FORGET";
+            MEMORY: "MEMORY";
+            APPLIED: "APPLIED";
+            REPLICATED: "REPLICATED";
+            PERSISTED: "PERSISTED";
+        }>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 declare const SyncInitMessageSchema: z.ZodObject<{
@@ -732,6 +805,16 @@ declare const PongMessageSchema: z.ZodObject<{
     timestamp: z.ZodNumber;
     serverTime: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * BATCH: Server sends multiple messages batched together.
+ * Uses length-prefixed binary format for efficiency.
+ * Format: [4 bytes: count][4 bytes: len1][msg1][4 bytes: len2][msg2]...
+ */
+declare const BatchMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"BATCH">;
+    count: z.ZodNumber;
+    data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
 /**
  * ORMAP_SYNC_INIT: Client initiates ORMap sync
  * Sends root hash and bucket hashes to server
@@ -859,6 +942,61 @@ declare const ORMapPushDiffSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * Individual operation result within a batch ACK
+ */
+declare const OpResultSchema: z.ZodObject<{
+    opId: z.ZodString;
+    success: z.ZodBoolean;
+    achievedLevel: z.ZodEnum<{
+        FIRE_AND_FORGET: "FIRE_AND_FORGET";
+        MEMORY: "MEMORY";
+        APPLIED: "APPLIED";
+        REPLICATED: "REPLICATED";
+        PERSISTED: "PERSISTED";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * OP_ACK: Server acknowledges write operations
+ * Extended to support Write Concern levels
+ */
+declare const OpAckMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"OP_ACK">;
+    payload: z.ZodObject<{
+        lastId: z.ZodString;
+        achievedLevel: z.ZodOptional<z.ZodEnum<{
+            FIRE_AND_FORGET: "FIRE_AND_FORGET";
+            MEMORY: "MEMORY";
+            APPLIED: "APPLIED";
+            REPLICATED: "REPLICATED";
+            PERSISTED: "PERSISTED";
+        }>>;
+        results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            opId: z.ZodString;
+            success: z.ZodBoolean;
+            achievedLevel: z.ZodEnum<{
+                FIRE_AND_FORGET: "FIRE_AND_FORGET";
+                MEMORY: "MEMORY";
+                APPLIED: "APPLIED";
+                REPLICATED: "REPLICATED";
+                PERSISTED: "PERSISTED";
+            }>;
+            error: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * OP_REJECTED: Server rejects a write operation
+ */
+declare const OpRejectedMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"OP_REJECTED">;
+    payload: z.ZodObject<{
+        opId: z.ZodString;
+        reason: z.ZodString;
+        code: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 declare const MessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"AUTH">;
     token: z.ZodString;
@@ -910,6 +1048,14 @@ declare const MessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             ttlMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
         orTag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        writeConcern: z.ZodOptional<z.ZodEnum<{
+            FIRE_AND_FORGET: "FIRE_AND_FORGET";
+            MEMORY: "MEMORY";
+            APPLIED: "APPLIED";
+            REPLICATED: "REPLICATED";
+            PERSISTED: "PERSISTED";
+        }>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"OP_BATCH">;
@@ -939,7 +1085,23 @@ declare const MessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 ttlMs: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>>;
             orTag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            writeConcern: z.ZodOptional<z.ZodEnum<{
+                FIRE_AND_FORGET: "FIRE_AND_FORGET";
+                MEMORY: "MEMORY";
+                APPLIED: "APPLIED";
+                REPLICATED: "REPLICATED";
+                PERSISTED: "PERSISTED";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
+        writeConcern: z.ZodOptional<z.ZodEnum<{
+            FIRE_AND_FORGET: "FIRE_AND_FORGET";
+            MEMORY: "MEMORY";
+            APPLIED: "APPLIED";
+            REPLICATED: "REPLICATED";
+            PERSISTED: "PERSISTED";
+        }>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"SYNC_INIT">;
@@ -1124,5 +1286,135 @@ type ClientOp = z.infer<typeof ClientOpSchema>;
 type Message = z.infer<typeof MessageSchema>;
 type PingMessage = z.infer<typeof PingMessageSchema>;
 type PongMessage = z.infer<typeof PongMessageSchema>;
+type BatchMessage = z.infer<typeof BatchMessageSchema>;
+type OpAckMessage = z.infer<typeof OpAckMessageSchema>;
+type OpRejectedMessage = z.infer<typeof OpRejectedMessageSchema>;
+type OpResult = z.infer<typeof OpResultSchema>;
+
+/**
+ * Write Concern - Configurable Acknowledgment Levels
+ *
+ * Write Concern defines when a write operation is considered successful.
+ * Similar to MongoDB's writeConcern, Kafka's acks, and Cassandra's consistency levels.
+ */
+/**
+ * Write Concern levels - determines when an operation is acknowledged.
+ *
+ * Levels are ordered by durability guarantee (lowest to highest):
+ * FIRE_AND_FORGET < MEMORY < APPLIED < REPLICATED < PERSISTED
+ */
+declare enum WriteConcern {
+    /**
+     * FIRE_AND_FORGET (acks=0)
+     * - ACK sent immediately after server receives the message
+     * - Operation may be lost if server crashes before processing
+     * - Maximum throughput, minimum latency
+     * - Use case: metrics, logs, non-critical data
+     */
+    FIRE_AND_FORGET = "FIRE_AND_FORGET",
+    /**
+     * MEMORY (acks=1, default) - current Early ACK behavior
+     * - ACK sent after validation and queuing for processing
+     * - Operation is in memory but not yet applied to CRDT
+     * - Use case: most operations, real-time updates
+     */
+    MEMORY = "MEMORY",
+    /**
+     * APPLIED
+     * - ACK sent after operation is applied to CRDT in memory
+     * - Data is readable on this node immediately after ACK
+     * - Use case: operations requiring immediate consistency on the node
+     */
+    APPLIED = "APPLIED",
+    /**
+     * REPLICATED
+     * - ACK sent after operation is broadcast to cluster (CLUSTER_EVENT sent)
+     * - Data survives primary node failure
+     * - Use case: important data requiring cluster durability
+     */
+    REPLICATED = "REPLICATED",
+    /**
+     * PERSISTED
+     * - ACK sent after operation is written to storage on primary node
+     * - Data survives node restart
+     * - Use case: critical data (financial transactions, audit logs)
+     */
+    PERSISTED = "PERSISTED"
+}
+/**
+ * Default timeout for Write Concern acknowledgments (ms)
+ */
+declare const DEFAULT_WRITE_CONCERN_TIMEOUT = 5000;
+/**
+ * Write options for PUT/REMOVE operations
+ */
+interface WriteOptions {
+    /**
+     * Write acknowledgment level.
+     * @default WriteConcern.MEMORY
+     */
+    writeConcern?: WriteConcern;
+    /**
+     * Timeout for waiting for acknowledgment (ms).
+     * Applies to APPLIED, REPLICATED, PERSISTED levels.
+     * @default 5000
+     */
+    timeout?: number;
+}
+/**
+ * Result of a write operation
+ */
+interface WriteResult {
+    /** Whether the operation achieved the requested Write Concern level */
+    success: boolean;
+    /** Operation ID */
+    opId: string;
+    /** The Write Concern level actually achieved */
+    achievedLevel: WriteConcern;
+    /** Time taken to achieve the level (ms) */
+    latencyMs: number;
+    /** Error message if success=false */
+    error?: string;
+}
+/**
+ * Internal structure for tracking pending write acknowledgments
+ */
+interface PendingWrite {
+    /** Operation ID */
+    opId: string;
+    /** Target Write Concern level */
+    writeConcern: WriteConcern;
+    /** Timestamp when operation was registered */
+    timestamp: number;
+    /** Timeout duration (ms) */
+    timeout: number;
+    /** Promise resolve callback */
+    resolve: (result: WriteResult) => void;
+    /** Promise reject callback */
+    reject: (error: Error) => void;
+    /** Timeout handle for cleanup */
+    timeoutHandle?: ReturnType<typeof setTimeout>;
+    /** Set of levels that have been achieved */
+    achievedLevels: Set<WriteConcern>;
+}
+/**
+ * Ordered list of Write Concern levels (lowest to highest)
+ */
+declare const WRITE_CONCERN_ORDER: readonly WriteConcern[];
+/**
+ * Check if a target Write Concern level is achieved based on achieved levels.
+ *
+ * @param achieved - Set of achieved Write Concern levels
+ * @param target - Target Write Concern level to check
+ * @returns true if target level (or higher) is achieved
+ */
+declare function isWriteConcernAchieved(achieved: Set<WriteConcern>, target: WriteConcern): boolean;
+/**
+ * Get the highest achieved Write Concern level from a set of achieved levels.
+ *
+ * @param achieved - Set of achieved Write Concern levels
+ * @returns The highest achieved level
+ */
+declare function getHighestWriteConcernLevel(achieved: Set<WriteConcern>): WriteConcern;
 
-export { AuthMessageSchema, type ClientOp, ClientOpMessageSchema, ClientOpSchema, HLC, LWWMap, type LWWRecord, LWWRecordSchema, LockReleaseSchema, LockRequestSchema, type MergeKeyResult, MerkleReqBucketMessageSchema, MerkleTree, type Message, MessageSchema, ORMap, ORMapDiffRequestSchema, ORMapDiffResponseSchema, type ORMapMerkleNode, ORMapMerkleReqBucketSchema, ORMapMerkleTree, ORMapPushDiffSchema, type ORMapRecord, ORMapRecordSchema, type ORMapSnapshot, ORMapSyncInitSchema, ORMapSyncRespBucketsSchema, ORMapSyncRespLeafSchema, ORMapSyncRespRootSchema, OpBatchMessageSchema, type PermissionPolicy, type PermissionType, type PingMessage, PingMessageSchema, type PongMessage, PongMessageSchema, type PredicateNode, PredicateNodeSchema, type PredicateOp, PredicateOpSchema, Predicates, type Principal, type Query, QuerySchema, QuerySubMessageSchema, QueryUnsubMessageSchema, SyncInitMessageSchema, SyncRespBucketsMessageSchema, SyncRespLeafMessageSchema, SyncRespRootMessageSchema, type Timestamp, TimestampSchema, TopicMessageEventSchema, TopicPubSchema, TopicSubSchema, TopicUnsubSchema, combineHashes, compareTimestamps, deserialize, evaluatePredicate, hashORMapEntry, hashORMapRecord, hashString, serialize, timestampToString };
+export { AuthMessageSchema, type BatchMessage, BatchMessageSchema, type ClientOp, ClientOpMessageSchema, ClientOpSchema, DEFAULT_WRITE_CONCERN_TIMEOUT, HLC, LWWMap, type LWWRecord, LWWRecordSchema, LockReleaseSchema, LockRequestSchema, type MergeKeyResult, MerkleReqBucketMessageSchema, MerkleTree, type Message, MessageSchema, ORMap, ORMapDiffRequestSchema, ORMapDiffResponseSchema, type ORMapMerkleNode, ORMapMerkleReqBucketSchema, ORMapMerkleTree, ORMapPushDiffSchema, type ORMapRecord, ORMapRecordSchema, type ORMapSnapshot, ORMapSyncInitSchema, ORMapSyncRespBucketsSchema, ORMapSyncRespLeafSchema, ORMapSyncRespRootSchema, type OpAckMessage, OpAckMessageSchema, OpBatchMessageSchema, type OpRejectedMessage, OpRejectedMessageSchema, type OpResult, OpResultSchema, type PendingWrite, type PermissionPolicy, type PermissionType, type PingMessage, PingMessageSchema, type PongMessage, PongMessageSchema, type PredicateNode, PredicateNodeSchema, type PredicateOp, PredicateOpSchema, Predicates, type Principal, type Query, QuerySchema, QuerySubMessageSchema, QueryUnsubMessageSchema, SyncInitMessageSchema, SyncRespBucketsMessageSchema, SyncRespLeafMessageSchema, SyncRespRootMessageSchema, type Timestamp, TimestampSchema, TopicMessageEventSchema, TopicPubSchema, TopicSubSchema, TopicUnsubSchema, WRITE_CONCERN_ORDER, WriteConcern, WriteConcernSchema, type WriteConcernValue, type WriteOptions, type WriteResult, combineHashes, compareTimestamps, deserialize, disableNativeHash, evaluatePredicate, getHighestWriteConcernLevel, hashORMapEntry, hashORMapRecord, hashString, isUsingNativeHash, isWriteConcernAchieved, resetNativeHash, serialize, timestampToString };