@wardx/core 0.7.0 → 0.9.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.
@@ -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.7.0",
+  "version": "0.9.0",
   "description": "Runtime-agnostic Wardx engine for metrics, events, logs, Remote Config, and experiments.",
   "keywords": [
     "wardx",

package/src/config/hash.js

@@ -1,6 +1,6 @@
 import xxhash from 'xxhash-wasm';
 
-const { h64ToString } = await xxhash();
+const { h64 } = await xxhash();
 
 const encoder = new TextEncoder();
 
@@ -26,6 +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 h64ToString(`${projectSalt}\0${subjectId}`);
+  return subjectHash64(projectSalt, subjectId).toString(16).padStart(16, '0');
 }

package/src/index.d.ts

@@ -67,6 +67,8 @@ export interface SdkDefaults {
 }
 
 export interface CreateWardxOptions extends Partial<SdkDefaults> {
+  attributes?: Record<string, string | number | boolean>;
+  enabled?: boolean;
   endpoint: string;
   projectKey: string;
   project: string;
@@ -89,6 +91,8 @@ export interface CoreSettings extends SdkDefaults {
 }
 
 export interface ResolvedSettings extends SdkDefaults {
+  attributes?: Record<string, string | number | boolean>;
+  enabled?: boolean;
   endpoint: string;
   projectKey: string;
   project: string;

package/src/metrics/HyperLogLog.js

@@ -1,8 +1,9 @@
-import { subjectHash } from '../config/hash.js';
+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,8 +80,8 @@ export class HyperLogLog {
     if (typeof identifier !== 'string' || identifier.length === 0) {
       throw new Error('distinct.add requires a non-empty string');
     }
-    const digest = Buffer.from(subjectHash(this.privacySalt, identifier), 'hex');
-    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;