@wardx/core 0.5.0 → 0.8.0

package/README.md

@@ -79,11 +79,16 @@ const settings = {
 
 const core = new WardxCore(settings);
 
-core.counter('match.completed', { mode: 'ranked' }).inc();
-core.counter('coins.awarded').add(25);
-core.gauge('players.online').set(12921);
-core.histogram('request.duration').observe(42);
-core.distinct('shot.traffic.hids', { result: 'violating' }).add(hid);
+const completed = core.counter('match.completed', { mode: 'ranked' });
+completed.inc();
+const coinsAwarded = core.counter('coins.awarded');
+coinsAwarded.add(25);
+const playersOnline = core.gauge('players.online');
+playersOnline.set(12921);
+const requestDuration = core.histogram('request.duration');
+requestDuration.observe(42);
+const shotTrafficHids = core.distinct('shot.traffic.hids', { result: 'violating' });
+shotTrafficHids.add(hid);
 
 const endTimer = core.timer('matchmaking.duration');
 endTimer({ result: 'success' });
@@ -108,8 +113,10 @@ const frames = core.takePendingFrames();
 `histogram(name).observe(value)` records a finite value into buckets. You can set buckets:
 
 ```js
-core.histogram('request.duration', { buckets: [10, 25, 50, 100] }).observe(42);
-core.histogram('coins.award_size').observe(80, { grantId: 'g-80' });
+const requestDuration = core.histogram('request.duration', { buckets: [10, 25, 50, 100] });
+requestDuration.observe(42);
+const coinsAwardSize = core.histogram('coins.award_size');
+coinsAwardSize.observe(80, { grantId: 'g-80' });
 ```
 
 `observe(value, attrs)` keeps `attrs` only when `value` is the window max. The frame stores that pair as `exemplar`. Attrs use the same key and value limits as dimensions. Do not change the buckets of an existing series. The engine throws an error.
@@ -117,7 +124,7 @@ core.histogram('coins.award_size').observe(80, { grantId: 'g-80' });
 `timer(name, dims)` starts a timer. The returned function records the duration in milliseconds into a histogram. You can add dimensions when you stop the timer.
 
 `distinct(name, dims).add(identifier)` updates a fixed HyperLogLog sketch. The
-engine hashes the identifier as `SHA-256(privacySalt || 0x00 || identifier)` and
+engine hashes the identifier as `XXHash64(privacySalt || 0x00 || identifier)` and
 discards it immediately; the frame contains only 512 HLL registers (`p=9`,
 about 4.6% standard error). Keep `privacySalt` stable across workers and time
 windows so equal identifiers map to equal registers.
@@ -239,7 +246,7 @@ bucket = hash / 2^32
 
 If `bucket >= allocation`, `assignVariant` returns `null`.
 
-`subjectHash` returns 64 lowercase hex digits of `SHA-256(UTF8(privacySalt) || 0x00 || UTF8(subjectId))`.
+`subjectHash` returns 16 lowercase hex digits of `XXHash64(UTF8(privacySalt) || 0x00 || UTF8(subjectId))`.
 
 ## Use case 5: Build a frame for a custom transport
 
@@ -250,7 +257,8 @@ If `bucket >= allocation`, `assignVariant` returns `null`.
 ```js
 import { FrameBuilder, PROTOCOL_VERSION, SDK_NAME, PLATFORM } from '@wardx/core';
 
-core.counter('match.completed').inc();
+const matchCompleted = core.counter('match.completed');
+matchCompleted.inc();
 const batch = core.snapshotIfDirty();
 if (batch) {
   const frames = core.takePendingFrames();
@@ -311,3 +319,13 @@ server persists UTC cohorts and exact received-user D1/D7/D30 returns; the core
 does not infer activity or keep a durable client identity/outbox. Use the same
 user ID and privacy salt across sessions and clients. See the
 [Node retention contract](../node/README.md#user-retention-d1--d7--d30).
+
+## Reuse metric handles
+
+Bind counters, gauges, histograms, and distinct handles once per stable name and
+dimension set. Keep them in the owning module or component and measure through
+the handles in callbacks. This avoids repeated dimension validation and registry
+lookup. Normal snapshots reset values while preserving handles; recreate bindings
+when replacing the core. Timer stop functions belong to individual operations.
+See the [Node pattern](../node/README.md#recommended-bind-once-measure-through-handles)
+and [C# field pattern](../../clients/csharp/README.md#recommended-keep-handles-as-fields).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardx/core",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Runtime-agnostic Wardx engine for metrics, events, logs, Remote Config, and experiments.",
   "keywords": [
     "wardx",
@@ -40,5 +40,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "xxhash-wasm": "1.1.0"
   }
 }

package/src/config/hash.js

@@ -1,4 +1,6 @@
-import { createHash } from 'node:crypto';
+import xxhash from 'xxhash-wasm';
+
+const { h64 } = await xxhash();
 
 const encoder = new TextEncoder();
 
@@ -24,10 +26,10 @@ export function assignmentHash(experimentId, subjectId, salt) {
   return fnv1a32(`${experimentId}:${subjectId}:${salt}`);
 }
 
+export function subjectHash64(projectSalt, subjectId) {
+  return h64(`${projectSalt}\0${subjectId}`);
+}
+
 export function subjectHash(projectSalt, subjectId) {
-  return createHash('sha256')
-    .update(projectSalt, 'utf8')
-    .update('\0', 'utf8')
-    .update(subjectId, 'utf8')
-    .digest('hex');
+  return subjectHash64(projectSalt, subjectId).toString(16).padStart(16, '0');
 }

package/src/index.d.ts

@@ -67,6 +67,7 @@ export interface SdkDefaults {
 }
 
 export interface CreateWardxOptions extends Partial<SdkDefaults> {
+  enabled?: boolean;
   endpoint: string;
   projectKey: string;
   project: string;
@@ -89,6 +90,7 @@ export interface CoreSettings extends SdkDefaults {
 }
 
 export interface ResolvedSettings extends SdkDefaults {
+  enabled?: boolean;
   endpoint: string;
   projectKey: string;
   project: string;

package/src/metrics/HyperLogLog.js

@@ -1,8 +1,9 @@
-import { createHash } from 'node:crypto';
+import { subjectHash64 } from '../config/hash.js';
 
 export const HLL_PRECISION = 9;
 export const HLL_REGISTER_COUNT = 1 << HLL_PRECISION;
 export const HLL_MAX_RANK = 64 - HLL_PRECISION + 1;
+const INDEX_SHIFT = BigInt(64 - HLL_PRECISION);
 
 function assertRegisters(registers) {
   if (!(registers instanceof Uint8Array) || registers.length !== HLL_REGISTER_COUNT) {
@@ -13,13 +14,10 @@ function assertRegisters(registers) {
   }
 }
 
-function rankAfterIndex(digest) {
-  let rank = 1;
-  for (let bit = HLL_PRECISION; bit < 64; bit++) {
-    if ((digest[bit >> 3] & (1 << (7 - (bit & 7)))) !== 0) return rank;
-    rank += 1;
-  }
-  return rank;
+export function rankAfterIndex(digest) {
+  const remainingHigh = Number(digest >> 32n) << HLL_PRECISION;
+  if (remainingHigh !== 0) return Math.clz32(remainingHigh) + 1;
+  return 32 - HLL_PRECISION + Math.clz32(Number(digest & 0xffffffffn)) + 1;
 }
 
 export function encodeHllRegisters(registers) {
@@ -82,12 +80,8 @@ export class HyperLogLog {
     if (typeof identifier !== 'string' || identifier.length === 0) {
       throw new Error('distinct.add requires a non-empty string');
     }
-    const digest = createHash('sha256')
-      .update(this.privacySalt, 'utf8')
-      .update('\0', 'utf8')
-      .update(identifier, 'utf8')
-      .digest();
-    const index = (digest[0] << 1) | (digest[1] >> 7);
+    const digest = subjectHash64(this.privacySalt, identifier);
+    const index = Number(digest >> INDEX_SHIFT);
     const rank = rankAfterIndex(digest);
     if (rank > this.registers[index]) this.registers[index] = rank;
     this.dirty = true;