@xnetjs/core 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -864,6 +864,96 @@ declare function validateExternalUrl(rawUrl: string): {
     error?: string;
 };
 
+/**
+ * Retry/backoff policies (exploration 0300).
+ *
+ * One dependency-free vocabulary for every reconnect/retry loop in the repo,
+ * replacing the hand-rolled backoff math that had drifted into three parallel
+ * implementations (sync connection-manager, WebSocketSyncProvider, webhook
+ * emitter). Deliberately shaped like Effect's `Schedule` combinators so a
+ * later migration would be mechanical — but scope-guarded: if this module
+ * needs union/intersect/cron/hedging, stop and re-read exploration 0300.
+ */
+/**
+ * A retry policy maps a 1-based attempt number to the delay (in ms) to wait
+ * before that attempt, or `null` to give up retrying.
+ */
+interface RetryPolicy {
+    /** Delay in ms before the given 1-based attempt, or `null` to give up. */
+    delayFor(attempt: number): number | null;
+}
+/** The same delay before every attempt. */
+declare function fixed(delayMs: number): RetryPolicy;
+/**
+ * Exponential backoff: `baseMs * factor^(attempt - 1)`.
+ * Attempt 1 waits `baseMs`, attempt 2 waits `baseMs * factor`, and so on.
+ */
+declare function exponential(baseMs: number, factor?: number): RetryPolicy;
+/** Cap another policy's delay at `maxDelayMs`. Passes `null` (give up) through. */
+declare function capped(policy: RetryPolicy, maxDelayMs: number): RetryPolicy;
+/**
+ * Add random jitter on top of another policy's delay: `delay + floor(random()
+ * * delay * ratio)`, i.e. up to `ratio` extra. Matches the hub rate-limit
+ * backoff behavior (exploration 0206) at the default `ratio` of 0.5. Passes
+ * `null` (give up) through. `random` is injectable for deterministic tests.
+ */
+declare function jittered(policy: RetryPolicy, ratio?: number, random?: () => number): RetryPolicy;
+/** Give up (return `null`) once `attempt` exceeds `maxAttempts`. */
+declare function limitAttempts(policy: RetryPolicy, maxAttempts: number): RetryPolicy;
+
+/**
+ * Tagged errors (exploration 0300).
+ *
+ * The repo-wide convention for structured errors, formalizing what
+ * `NodeRelayError.code` and friends already did by hand: every structured
+ * error carries a string-literal `_tag` discriminant so catch sites can
+ * narrow exhaustively instead of sniffing `instanceof` chains or message
+ * strings. Deliberately shaped like Effect's `Data.TaggedError` so a later
+ * migration would be mechanical.
+ *
+ * Convention (see CLAUDE.md): new structured errors extend `TaggedError`,
+ * set `_tag` to the class name, and put machine-readable context in readonly
+ * fields (a `code` union where one error class spans several failure kinds).
+ * Existing error classes migrate on touch, not as a campaign.
+ */
+declare abstract class TaggedError<Tag extends string = string> extends Error {
+    /** String-literal discriminant — by convention the class name. */
+    abstract readonly _tag: Tag;
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Narrow an unknown catch value to a specific tagged error. */
+declare function isTagged<Tag extends string>(error: unknown, tag: Tag): error is TaggedError<Tag>;
+
+/**
+ * Single-flight promise memoization (exploration 0300).
+ *
+ * The one implementation of the "share the in-flight promise so concurrent
+ * callers don't convoy the backend" pattern that had been independently
+ * hand-rolled at several call sites (schema registry lazy loads, sqlite
+ * adapter EXPLAIN diagnostics — explorations 0271/0276).
+ *
+ * The caller owns the map, so lifetime policy (instance field vs module
+ * scope), size caps, and explicit invalidation stay at the call site.
+ */
+interface SingleFlightOptions {
+    /**
+     * What happens to the map entry after the promise settles:
+     *
+     * - `'settled'` (default): the entry is removed once the promise settles —
+     *   the map only ever holds in-flight work (dedupe, not a cache).
+     * - `'keep'`: the entry stays after success, memoizing the result until the
+     *   caller evicts it. Rejections are always removed, so a failure never
+     *   poisons the key and the next caller retries.
+     */
+    retain?: 'settled' | 'keep';
+}
+/**
+ * Return the in-flight promise for `key` if one exists; otherwise start
+ * `fn()`, store its promise in `map`, and return it. Entry lifetime after
+ * settling is controlled by {@link SingleFlightOptions.retain}.
+ */
+declare function singleFlight<K, V>(map: Map<K, Promise<V>>, key: K, fn: () => Promise<V>, options?: SingleFlightOptions): Promise<V>;
+
 /**
  * The ONE Last-Write-Wins ordering for xNet (docs/specs/protocol §L1.7,
  * exploration 0276).
@@ -926,4 +1016,4 @@ declare function lwwUpdateGuardSql(input: {
 type DID = `did:key:${string}`;
 type DocumentPath = `xnet://${DID}/workspace/${string}/doc/${string}`;
 
-export { ALL_CAPABILITIES, AUTH_ACTIONS, type ActionKey, type AllowExpr, type AndExpr, type AuthAction, type AuthCheckInput, type AuthDecision, type AuthDenyReason, type AuthExpression, type AuthTrace, type AuthTraceStep, type AuthenticatedExpr, type AuthorizationDefinition, BOOTSTRAP_PEERS, type Capability, type ChainStatus, type Condition, type ContentChunk, type ContentId, type ContentResolver, type ContentTree, type CreatorRoleResolver, DEFAULT_SNAPSHOT_TRIGGERS, DEFAULT_STREAMING_OPTIONS, DHT_CONFIG, type DID, type DIDResolution, type DIDResolver, type DataSource, type DenyExpr, type DocumentLoad, type DocumentPath, type Fork, type Group, type IPCondition, type LwwStamp, type MembershipRoleResolver, type MerkleNode, type NotExpr, type OrExpr, type PeerLocation, type PermissionEvaluator, type PermissionGrant, type PolicyEvaluator, type PropertyRoleResolver, type PublicExpr, type Query, type QueryPlan, type QueryRequest, type QueryResponse, type QueryRouter, RESOLUTION_CACHE_CONFIG, type RelationRoleResolver, type ResolutionStrategy, type ResourceScope, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type Snapshot, type SnapshotTriggers, SsrfError, type StreamingQueryOptions, type SubQuery, type TimeCondition, type UpdateVerifier, type VectorClock, assertPublicUrl, buildMerkleTree, clamp, clamp01, compareChangeApplicationOrder, compareLwwStamps, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, formatBytes, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isValidDID, isValidProgression, lwwUpdateGuardSql, lwwWins, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, unionAggregate, validateExternalUrl, verifyContent, verifyUpdateChain };
+export { ALL_CAPABILITIES, AUTH_ACTIONS, type ActionKey, type AllowExpr, type AndExpr, type AuthAction, type AuthCheckInput, type AuthDecision, type AuthDenyReason, type AuthExpression, type AuthTrace, type AuthTraceStep, type AuthenticatedExpr, type AuthorizationDefinition, BOOTSTRAP_PEERS, type Capability, type ChainStatus, type Condition, type ContentChunk, type ContentId, type ContentResolver, type ContentTree, type CreatorRoleResolver, DEFAULT_SNAPSHOT_TRIGGERS, DEFAULT_STREAMING_OPTIONS, DHT_CONFIG, type DID, type DIDResolution, type DIDResolver, type DataSource, type DenyExpr, type DocumentLoad, type DocumentPath, type Fork, type Group, type IPCondition, type LwwStamp, type MembershipRoleResolver, type MerkleNode, type NotExpr, type OrExpr, type PeerLocation, type PermissionEvaluator, type PermissionGrant, type PolicyEvaluator, type PropertyRoleResolver, type PublicExpr, type Query, type QueryPlan, type QueryRequest, type QueryResponse, type QueryRouter, RESOLUTION_CACHE_CONFIG, type RelationRoleResolver, type ResolutionStrategy, type ResourceScope, type RetryPolicy, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type SingleFlightOptions, type Snapshot, type SnapshotTriggers, SsrfError, type StreamingQueryOptions, type SubQuery, TaggedError, type TimeCondition, type UpdateVerifier, type VectorClock, assertPublicUrl, buildMerkleTree, capped, clamp, clamp01, compareChangeApplicationOrder, compareLwwStamps, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, exponential, fixed, formatBytes, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isTagged, isValidDID, isValidProgression, jittered, limitAttempts, lwwUpdateGuardSql, lwwWins, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, singleFlight, unionAggregate, validateExternalUrl, verifyContent, verifyUpdateChain };

package/dist/index.js

@@ -408,6 +408,67 @@ function validateExternalUrl(rawUrl) {
   }
 }
 
+// src/retry/policy.ts
+function fixed(delayMs) {
+  return {
+    delayFor: () => delayMs
+  };
+}
+function exponential(baseMs, factor = 2) {
+  return {
+    delayFor: (attempt) => baseMs * factor ** (attempt - 1)
+  };
+}
+function capped(policy, maxDelayMs) {
+  return {
+    delayFor: (attempt) => {
+      const delay = policy.delayFor(attempt);
+      return delay === null ? null : Math.min(delay, maxDelayMs);
+    }
+  };
+}
+function jittered(policy, ratio = 0.5, random = Math.random) {
+  return {
+    delayFor: (attempt) => {
+      const delay = policy.delayFor(attempt);
+      return delay === null ? null : delay + Math.floor(random() * delay * ratio);
+    }
+  };
+}
+function limitAttempts(policy, maxAttempts) {
+  return {
+    delayFor: (attempt) => attempt > maxAttempts ? null : policy.delayFor(attempt)
+  };
+}
+
+// src/errors/tagged.ts
+var TaggedError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+function isTagged(error, tag) {
+  return error instanceof TaggedError && error._tag === tag;
+}
+
+// src/async/single-flight.ts
+function singleFlight(map, key, fn, options = {}) {
+  const existing = map.get(key);
+  if (existing) return existing;
+  const promise = fn();
+  map.set(key, promise);
+  const evict = () => {
+    if (map.get(key) === promise) map.delete(key);
+  };
+  if ((options.retain ?? "settled") === "settled") {
+    promise.then(evict, evict);
+  } else {
+    promise.then(void 0, evict);
+  }
+  return promise;
+}
+
 // src/lww.ts
 function compareLwwStamps(a, b) {
   if (a.lamport !== b.lamport) return a.lamport - b.lamport;
@@ -439,8 +500,10 @@ export {
   RESOLUTION_CACHE_CONFIG,
   STANDARD_ROLES,
   SsrfError,
+  TaggedError,
   assertPublicUrl,
   buildMerkleTree,
+  capped,
   clamp,
   clamp01,
   compareChangeApplicationOrder,
@@ -452,13 +515,18 @@ export {
   detectFork,
   estimateQueryCost,
   evaluateCondition,
+  exponential,
+  fixed,
   formatBytes,
   getMostPermissiveCapability,
   hashContent,
   incrementVectorClock,
   isLocationFresh,
+  isTagged,
   isValidDID,
   isValidProgression,
+  jittered,
+  limitAttempts,
   lwwUpdateGuardSql,
   lwwWins,
   mergeStateVectors,
@@ -467,6 +535,7 @@ export {
   parseDID,
   roleHasCapability,
   shouldCreateSnapshot,
+  singleFlight,
   unionAggregate,
   validateExternalUrl,
   verifyContent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/core",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,6 +25,7 @@
     "provenance": true
   },
   "devDependencies": {
+    "fast-check": "^4.8.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0"
   },