@fintekkers/ledger-models 0.4.9 → 0.4.11

package/node/wrappers/util/link-cache.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRANSACTION = exports.PRICE = exports.PORTFOLIO = exports.SECURITY = exports.LinkCache = exports.DEFAULT_TTL_FOR_LATEST_MS = void 0;
+exports.TRANSACTION = exports.PRICE = exports.PORTFOLIO = exports.SECURITY = exports.LinkCache = exports.DEFAULT_MAX_ENTRIES = exports.DEFAULT_TTL_FOR_LATEST_MS = void 0;
 /**
  * LinkCache — process-wide cache of resolved proto bodies backing link-mode
  * wrappers. TypeScript mirror of `common.util.LinkCache` (Java) and
@@ -18,18 +18,29 @@ exports.TRANSACTION = exports.PRICE = exports.PORTFOLIO = exports.SECURITY = exp
  * Write semantics (`put`): newest-vintage wins. An older-vintage put does
  * not evict a newer cached entry.
  *
- * Later Portfolio can likely be 1 day, security 1 day, transaction 1 minute,
- * price 30 seconds — once per-entity TTLs are wired up, the shared singletons
- * below should be constructed with those values.
+ * Eviction: bounded LRU. When `put` causes the map to exceed `maxEntries`,
+ * the least-recently-used entry is removed. `get` bumps recency.
+ *
+ * Per-entity singletons SECURITY/PORTFOLIO/PRICE/TRANSACTION are tuned
+ * for the typical access pattern of each entity (Portfolio + Security
+ * change slowly so TTL is 1 day; Price + Transaction change quickly so
+ * TTL is short).
  */
 exports.DEFAULT_TTL_FOR_LATEST_MS = 600000;
+exports.DEFAULT_MAX_ENTRIES = 10000;
 class LinkCache {
-    constructor(ttlForLatestMs = exports.DEFAULT_TTL_FOR_LATEST_MS) {
+    constructor(ttlForLatestMs = exports.DEFAULT_TTL_FOR_LATEST_MS, maxEntries = exports.DEFAULT_MAX_ENTRIES) {
         this.ttlForLatestMs = ttlForLatestMs;
+        this.maxEntries = maxEntries;
+        // Map iteration order = insertion order in JS; on hit we delete+re-insert
+        // to bump recency, on overflow we drop the oldest (first) key.
         this.map = new Map();
         if (ttlForLatestMs < 0) {
             throw new Error(`ttlForLatestMs must be non-negative; got ${ttlForLatestMs}`);
         }
+        if (maxEntries <= 0) {
+            throw new Error(`maxEntries must be > 0; got ${maxEntries}`);
+        }
     }
     /**
      * @param uuidKey         the entity uuid rendered as a stable string key
@@ -47,23 +58,43 @@ class LinkCache {
             if (Date.now() - entry.cachedAtMs > this.ttlForLatestMs) {
                 return undefined;
             }
-            return entry.value;
         }
-        return this._sameAsOf(entry.asOf, requestedAsOf) ? entry.value : undefined;
+        else {
+            if (entry.asOf == null)
+                return undefined;
+            if (!this._sameAsOf(entry.asOf, requestedAsOf))
+                return undefined;
+        }
+        // Hit — bump recency.
+        this.map.delete(uuidKey);
+        this.map.set(uuidKey, entry);
+        return entry.value;
     }
     /**
      * Newest-wins write: if a cached entry for `uuidKey` already exists with
-     * an asOf strictly after the incoming asOf, the write is ignored.
+     * an asOf strictly after the incoming asOf, the write is ignored (but
+     * recency is still bumped — the caller saw a fresh reference).
      */
     put(uuidKey, value, asOf) {
-        if (!uuidKey || !value || !asOf) {
-            throw new Error(`uuidKey / value / asOf must all be set; got uuidKey=${uuidKey} value=${value ? '<non-null>' : 'null'} asOf=${asOf}`);
+        if (!uuidKey || !value) {
+            throw new Error(`uuidKey / value must be set; got uuidKey=${uuidKey} value=${value ? '<non-null>' : 'null'}`);
         }
         const existing = this.map.get(uuidKey);
-        if (existing && this._isStrictlyAfter(existing.asOf, asOf)) {
+        if (existing && existing.asOf != null && asOf != null && this._isStrictlyAfter(existing.asOf, asOf)) {
+            // Recency bump only — older vintage doesn't displace newer cached entry.
+            this.map.delete(uuidKey);
+            this.map.set(uuidKey, existing);
             return;
         }
+        if (this.map.has(uuidKey))
+            this.map.delete(uuidKey);
         this.map.set(uuidKey, { value, asOf, cachedAtMs: Date.now() });
+        while (this.map.size > this.maxEntries) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
     }
     evict(uuidKey) {
         this.map.delete(uuidKey);
@@ -85,8 +116,13 @@ class LinkCache {
     }
 }
 exports.LinkCache = LinkCache;
-exports.SECURITY = new LinkCache();
-exports.PORTFOLIO = new LinkCache();
-exports.PRICE = new LinkCache();
-exports.TRANSACTION = new LinkCache();
+// Per-entity singletons. Tuned for the access pattern of each entity:
+//   Portfolio / Security: 1-day TTL on null-as_of reads (entities change
+//       infrequently); large caps because the universe is large.
+//   Transaction: 1-minute TTL (high churn).
+//   Price: 30-second TTL (very high churn).
+exports.SECURITY = new LinkCache(86400000, 100000);
+exports.PORTFOLIO = new LinkCache(86400000, 10000);
+exports.PRICE = new LinkCache(30000, 200000);
+exports.TRANSACTION = new LinkCache(60000, 100000);
 //# sourceMappingURL=link-cache.js.map

package/node/wrappers/util/link-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"link-cache.js","sourceRoot":"","sources":["link-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"link-cache.js","sourceRoot":"","sources":["link-cache.ts"],"names":[],"mappings":"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"}

package/node/wrappers/util/link-cache.ts

@@ -21,27 +21,41 @@ import { ZonedDateTime } from '../models/utils/datetime';
  * Write semantics (`put`): newest-vintage wins. An older-vintage put does
  * not evict a newer cached entry.
  *
- * Later Portfolio can likely be 1 day, security 1 day, transaction 1 minute,
- * price 30 seconds — once per-entity TTLs are wired up, the shared singletons
- * below should be constructed with those values.
+ * Eviction: bounded LRU. When `put` causes the map to exceed `maxEntries`,
+ * the least-recently-used entry is removed. `get` bumps recency.
+ *
+ * Per-entity singletons SECURITY/PORTFOLIO/PRICE/TRANSACTION are tuned
+ * for the typical access pattern of each entity (Portfolio + Security
+ * change slowly so TTL is 1 day; Price + Transaction change quickly so
+ * TTL is short).
  */
 export const DEFAULT_TTL_FOR_LATEST_MS = 600_000;
+export const DEFAULT_MAX_ENTRIES = 10_000;
 
 interface CacheEntry<V> {
   value: V;
-  /** Bitemporal asOf carried by the cached value. */
-  asOf: ZonedDateTime;
+  /** Bitemporal asOf carried by the cached value; null when put with no asOf
+   *  (e.g. lazy resolve for a link with no explicit as_of). */
+  asOf: ZonedDateTime | null;
   /** Wall-clock ms at the moment this entry was cached. */
   cachedAtMs: number;
 }
 
 export class LinkCache<V> {
+  // Map iteration order = insertion order in JS; on hit we delete+re-insert
+  // to bump recency, on overflow we drop the oldest (first) key.
   private map = new Map<string, CacheEntry<V>>();
 
-  constructor(private ttlForLatestMs: number = DEFAULT_TTL_FOR_LATEST_MS) {
+  constructor(
+    private ttlForLatestMs: number = DEFAULT_TTL_FOR_LATEST_MS,
+    private maxEntries: number = DEFAULT_MAX_ENTRIES,
+  ) {
     if (ttlForLatestMs < 0) {
       throw new Error(`ttlForLatestMs must be non-negative; got ${ttlForLatestMs}`);
     }
+    if (maxEntries <= 0) {
+      throw new Error(`maxEntries must be > 0; got ${maxEntries}`);
+    }
   }
 
   /**
@@ -59,26 +73,41 @@ export class LinkCache<V> {
       if (Date.now() - entry.cachedAtMs > this.ttlForLatestMs) {
         return undefined;
       }
-      return entry.value;
+    } else {
+      if (entry.asOf == null) return undefined;
+      if (!this._sameAsOf(entry.asOf, requestedAsOf)) return undefined;
     }
-    return this._sameAsOf(entry.asOf, requestedAsOf) ? entry.value : undefined;
+    // Hit — bump recency.
+    this.map.delete(uuidKey);
+    this.map.set(uuidKey, entry);
+    return entry.value;
   }
 
   /**
    * Newest-wins write: if a cached entry for `uuidKey` already exists with
-   * an asOf strictly after the incoming asOf, the write is ignored.
+   * an asOf strictly after the incoming asOf, the write is ignored (but
+   * recency is still bumped — the caller saw a fresh reference).
    */
-  put(uuidKey: string, value: V, asOf: ZonedDateTime): void {
-    if (!uuidKey || !value || !asOf) {
+  put(uuidKey: string, value: V, asOf: ZonedDateTime | null): void {
+    if (!uuidKey || !value) {
       throw new Error(
-        `uuidKey / value / asOf must all be set; got uuidKey=${uuidKey} value=${value ? '<non-null>' : 'null'} asOf=${asOf}`
+        `uuidKey / value must be set; got uuidKey=${uuidKey} value=${value ? '<non-null>' : 'null'}`
       );
     }
     const existing = this.map.get(uuidKey);
-    if (existing && this._isStrictlyAfter(existing.asOf, asOf)) {
+    if (existing && existing.asOf != null && asOf != null && this._isStrictlyAfter(existing.asOf, asOf)) {
+      // Recency bump only — older vintage doesn't displace newer cached entry.
+      this.map.delete(uuidKey);
+      this.map.set(uuidKey, existing);
       return;
     }
+    if (this.map.has(uuidKey)) this.map.delete(uuidKey);
     this.map.set(uuidKey, { value, asOf, cachedAtMs: Date.now() });
+    while (this.map.size > this.maxEntries) {
+      const oldest = this.map.keys().next().value;
+      if (oldest === undefined) break;
+      this.map.delete(oldest);
+    }
   }
 
   evict(uuidKey: string): void {
@@ -104,7 +133,12 @@ export class LinkCache<V> {
   }
 }
 
-export const SECURITY = new LinkCache<SecurityProto>();
-export const PORTFOLIO = new LinkCache<PortfolioProto>();
-export const PRICE = new LinkCache<PriceProto>();
-export const TRANSACTION = new LinkCache<TransactionProto>();
+// Per-entity singletons. Tuned for the access pattern of each entity:
+//   Portfolio / Security: 1-day TTL on null-as_of reads (entities change
+//       infrequently); large caps because the universe is large.
+//   Transaction: 1-minute TTL (high churn).
+//   Price: 30-second TTL (very high churn).
+export const SECURITY = new LinkCache<SecurityProto>(86_400_000, 100_000);
+export const PORTFOLIO = new LinkCache<PortfolioProto>(86_400_000, 10_000);
+export const PRICE = new LinkCache<PriceProto>(30_000, 200_000);
+export const TRANSACTION = new LinkCache<TransactionProto>(60_000, 100_000);

package/node/wrappers/util/link-resolver.d.ts

@@ -3,41 +3,33 @@ import { PortfolioProto } from '../../fintekkers/models/portfolio/portfolio_pb';
 import { LocalTimestampProto } from '../../fintekkers/models/util/local_timestamp_pb';
 import { SecurityClient } from '../../fintekkers/services/security-service/security_service_grpc_pb';
 import { PortfolioClient } from '../../fintekkers/services/portfolio-service/portfolio_service_grpc_pb';
+import { TransactionClient } from '../../fintekkers/services/transaction-service/transaction_service_grpc_pb';
 import Security from '../models/security/security';
 import Portfolio from '../models/portfolio/portfolio';
+import Transaction from '../models/transaction/transaction';
 import { UUID } from '../models/utils/uuid';
 /**
  * LinkResolver — bulk hydration of `is_link=true` entity references into
  * full entities. Implements the consumer side of the `is_link` pattern
  * documented in `docs/adr/is_link_pattern.md`.
  *
+ * W4: the resolver no longer owns its own LRU. Cache reads/writes route
+ * through the process-wide `LinkCache.SECURITY` / `LinkCache.PORTFOLIO`
+ * singletons. The resolver still does concurrent-call dedup (single
+ * in-flight RPC per (uuid, as_of)) and bulk per-bucket batching; storage
+ * and eviction live in LinkCache.
+ *
  * Two surface methods:
  *   - getSecurity(uuid) / getPortfolio(uuid): single-UUID resolution. Cached
  *     and concurrent-deduped.
  *   - resolveSecurities(items) / resolvePortfolios(items): bulk in-place
  *     mutation across a heterogeneous list of items that each have a
  *     proto-style getter+setter for the embedded entity. Collects unique
- *     link UUIDs, fires one batched GetByIds RPC, mutates each item's proto
- *     to swap the link sub-message for the resolved full entity (with
- *     is_link=false on the embedded copy).
- *
- * Caching:
- *   - Process-level LRU keyed on UUID string. Default 1000 entries, no TTL
- *     (entries live until evicted by LRU). Long-running services that need
- *     freshness should pass `{ ttlMs: <ms> }`. Tests can disable with
- *     `{ cacheSize: 0 }`.
- *   - Concurrent same-UUID requests are deduped via an in-flight promise
- *     map — N parallel callers for the same UUID share one RPC.
- *
- * RPC choice: uses `GetByIds` (unary, UUID-keyed bulk) per the ADR. The
- * existing `SecurityService.search` (streaming) would also work but
- * requires more wrapper plumbing for batched-by-UUID semantics.
+ *     link UUIDs, fires one batched GetByIds RPC per as_of bucket, mutates
+ *     each item's proto to swap the link sub-message for the resolved
+ *     full entity.
  *
- * Mutation semantic: when bulk-resolving, the embedded sub-message is
- * replaced (not the outer entity). Outer Price.proto.is_link is unchanged;
- * only the inner SecurityProto is swapped from link-stub to full entity.
- * Wrapper objects that read through the proto (`price.getSecurity()`)
- * automatically see the resolved data.
+ * RPC choice: uses `GetByIds` (unary, UUID-keyed bulk) per the ADR.
  *
  * Time-travel (`as_of`) semantic: per is_link_pattern.md addendum, when
  * a link sub-message has only `uuid` set the resolver fetches the latest
@@ -50,24 +42,35 @@ import { UUID } from '../models/utils/uuid';
 export interface LinkResolverOptions {
     /** Optional API key. If omitted, EnvConfig.apiCredentials is used. */
     apiKey?: string;
-    /** LRU max entries. Default 1000. Set to 0 to disable caching. */
-    cacheSize?: number;
-    /** Per-entry TTL in ms. Default undefined (no expiry). */
-    ttlMs?: number;
     /**
      * Test injection: clients to use instead of constructing real ones.
      * Production callers should not set these.
      */
     securityClient?: SecurityClient;
     portfolioClient?: PortfolioClient;
+    transactionClient?: TransactionClient;
 }
 declare class LinkResolver {
     private securityClient;
     private portfolioClient;
-    private securityCache;
-    private portfolioCache;
+    private transactionClient;
     private securityInFlight;
     private portfolioInFlight;
+    private transactionInFlight;
+    /**
+     * Process-wide singleton — lazily constructed with default options
+     * (env-derived endpoint via `EnvConfig`). The wrapper `hydrate()`
+     * methods reach for this when no resolver is passed explicitly, so
+     * users get auto-resolve on link-mode wrappers without threading a
+     * resolver through every call site.
+     */
+    static getDefault(): LinkResolver;
+    /**
+     * Replace the process-wide default. Call once at process start for
+     * tests with mocked clients or to point at a non-default endpoint.
+     * Pass `undefined` to clear (next `getDefault()` call rebuilds).
+     */
+    static setDefault(resolver: LinkResolver | undefined): void;
     constructor(opts?: LinkResolverOptions);
     /**
      * Resolve a single SecurityProto by UUID. If `asOf` is supplied, fetch
@@ -81,6 +84,11 @@ declare class LinkResolver {
      * Cached + concurrent-deduped on (uuid, asOf).
      */
     getPortfolio(uuid: UUID, asOf?: LocalTimestampProto): Promise<Portfolio>;
+    /**
+     * Resolve a single TransactionProto by UUID, optionally as of `asOf`.
+     * Cached + concurrent-deduped on (uuid, asOf).
+     */
+    getTransaction(uuid: UUID, asOf?: LocalTimestampProto): Promise<Transaction>;
     /**
      * Walk `items`, find the ones whose embedded security is `is_link=true`,
      * batch-fetch the unique (uuid, as_of) pairs (grouped by as_of so each
@@ -88,10 +96,6 @@ declare class LinkResolver {
      * place so subsequent `item.getSecurity()` calls return the full entity.
      * Returns the same array for chaining.
      *
-     * Honors per-link `as_of`: if the embedded sub-message has `as_of` set,
-     * the resolver fetches the version of the entity at that timestamp,
-     * not the latest.
-     *
      * `T` is structural: anything with a `proto` field that exposes
      * `getSecurity()` / `setSecurity()` works (Price, Transaction, etc).
      */
@@ -101,11 +105,15 @@ declare class LinkResolver {
      * Honors per-link `as_of` the same way.
      */
     resolvePortfolios<T extends ResolvablePortfolio>(items: T[]): Promise<T[]>;
-    /** Test/debug helper. Not part of the stable API. */
+    /** Test/debug helper. Clears in-flight maps; the process-wide LinkCache
+     * is left alone (tests that need to drop a specific cached entry call
+     * `LinkCache.SECURITY.evict(uuid)` directly). */
     clearCache(): void;
     private fetchSecurityProto;
     private fetchPortfolioProto;
+    private fetchTransactionProto;
     private batchFetchSecurities;
+    private batchFetchTransactions;
     private batchFetchPortfolios;
 }
 /**