@cleocode/lafs 2026.3.74 → 2026.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/LICENSE +0 -0
  2. package/README.md +97 -68
  3. package/dist/schemas/v1/agent-card.schema.json +230 -0
  4. package/dist/schemas/v1/conformance-profiles.json +0 -0
  5. package/dist/schemas/v1/context-ledger.schema.json +70 -0
  6. package/dist/schemas/v1/discovery.schema.json +132 -0
  7. package/dist/schemas/v1/envelope.schema.json +0 -0
  8. package/dist/schemas/v1/error-registry.json +0 -0
  9. package/dist/src/a2a/bindings/grpc.d.ts +118 -11
  10. package/dist/src/a2a/bindings/grpc.d.ts.map +1 -0
  11. package/dist/src/a2a/bindings/grpc.js +80 -8
  12. package/dist/src/a2a/bindings/grpc.js.map +1 -0
  13. package/dist/src/a2a/bindings/http.d.ts +131 -15
  14. package/dist/src/a2a/bindings/http.d.ts.map +1 -0
  15. package/dist/src/a2a/bindings/http.js +101 -14
  16. package/dist/src/a2a/bindings/http.js.map +1 -0
  17. package/dist/src/a2a/bindings/index.d.ts +83 -9
  18. package/dist/src/a2a/bindings/index.d.ts.map +1 -0
  19. package/dist/src/a2a/bindings/index.js +74 -6
  20. package/dist/src/a2a/bindings/index.js.map +1 -0
  21. package/dist/src/a2a/bindings/jsonrpc.d.ts +194 -9
  22. package/dist/src/a2a/bindings/jsonrpc.d.ts.map +1 -0
  23. package/dist/src/a2a/bindings/jsonrpc.js +155 -10
  24. package/dist/src/a2a/bindings/jsonrpc.js.map +1 -0
  25. package/dist/src/a2a/bridge.d.ts +237 -44
  26. package/dist/src/a2a/bridge.d.ts.map +1 -0
  27. package/dist/src/a2a/bridge.js +187 -48
  28. package/dist/src/a2a/bridge.js.map +1 -0
  29. package/dist/src/a2a/extensions.d.ts +222 -12
  30. package/dist/src/a2a/extensions.d.ts.map +1 -0
  31. package/dist/src/a2a/extensions.js +178 -13
  32. package/dist/src/a2a/extensions.js.map +1 -0
  33. package/dist/src/a2a/index.d.ts +10 -7
  34. package/dist/src/a2a/index.d.ts.map +1 -0
  35. package/dist/src/a2a/index.js +24 -27
  36. package/dist/src/a2a/index.js.map +1 -0
  37. package/dist/src/a2a/streaming.d.ts +276 -3
  38. package/dist/src/a2a/streaming.d.ts.map +1 -0
  39. package/dist/src/a2a/streaming.js +255 -11
  40. package/dist/src/a2a/streaming.js.map +1 -0
  41. package/dist/src/a2a/task-lifecycle.d.ts +341 -20
  42. package/dist/src/a2a/task-lifecycle.d.ts.map +1 -0
  43. package/dist/src/a2a/task-lifecycle.js +327 -26
  44. package/dist/src/a2a/task-lifecycle.js.map +1 -0
  45. package/dist/src/budgetEnforcement.d.ts +93 -20
  46. package/dist/src/budgetEnforcement.d.ts.map +1 -0
  47. package/dist/src/budgetEnforcement.js +146 -31
  48. package/dist/src/budgetEnforcement.js.map +1 -0
  49. package/dist/src/circuit-breaker/index.d.ts +260 -10
  50. package/dist/src/circuit-breaker/index.d.ts.map +1 -0
  51. package/dist/src/circuit-breaker/index.js +226 -14
  52. package/dist/src/circuit-breaker/index.js.map +1 -0
  53. package/dist/src/cli.d.ts +1 -0
  54. package/dist/src/cli.d.ts.map +1 -0
  55. package/dist/src/cli.js +12 -11
  56. package/dist/src/cli.js.map +1 -0
  57. package/dist/src/compliance.d.ts +180 -3
  58. package/dist/src/compliance.d.ts.map +1 -0
  59. package/dist/src/compliance.js +114 -13
  60. package/dist/src/compliance.js.map +1 -0
  61. package/dist/src/conformance.d.ts +55 -2
  62. package/dist/src/conformance.d.ts.map +1 -0
  63. package/dist/src/conformance.js +124 -76
  64. package/dist/src/conformance.js.map +1 -0
  65. package/dist/src/conformanceProfiles.d.ts +68 -1
  66. package/dist/src/conformanceProfiles.d.ts.map +1 -0
  67. package/dist/src/conformanceProfiles.js +53 -1
  68. package/dist/src/conformanceProfiles.js.map +1 -0
  69. package/dist/src/deprecationRegistry.d.ts +82 -1
  70. package/dist/src/deprecationRegistry.d.ts.map +1 -0
  71. package/dist/src/deprecationRegistry.js +58 -7
  72. package/dist/src/deprecationRegistry.js.map +1 -0
  73. package/dist/src/discovery.d.ts +347 -65
  74. package/dist/src/discovery.d.ts.map +1 -0
  75. package/dist/src/discovery.js +130 -72
  76. package/dist/src/discovery.js.map +1 -0
  77. package/dist/src/envelope.d.ts +262 -9
  78. package/dist/src/envelope.d.ts.map +1 -0
  79. package/dist/src/envelope.js +179 -15
  80. package/dist/src/envelope.js.map +1 -0
  81. package/dist/src/errorRegistry.d.ts +163 -3
  82. package/dist/src/errorRegistry.d.ts.map +1 -0
  83. package/dist/src/errorRegistry.js +119 -3
  84. package/dist/src/errorRegistry.js.map +1 -0
  85. package/dist/src/fieldExtraction.d.ts +128 -27
  86. package/dist/src/fieldExtraction.d.ts.map +1 -0
  87. package/dist/src/fieldExtraction.js +100 -27
  88. package/dist/src/fieldExtraction.js.map +1 -0
  89. package/dist/src/flagResolver.d.ts +77 -10
  90. package/dist/src/flagResolver.d.ts.map +1 -0
  91. package/dist/src/flagResolver.js +22 -5
  92. package/dist/src/flagResolver.js.map +1 -0
  93. package/dist/src/flagSemantics.d.ts +80 -4
  94. package/dist/src/flagSemantics.d.ts.map +1 -0
  95. package/dist/src/flagSemantics.js +78 -11
  96. package/dist/src/flagSemantics.js.map +1 -0
  97. package/dist/src/health/index.d.ts +103 -9
  98. package/dist/src/health/index.d.ts.map +1 -0
  99. package/dist/src/health/index.js +75 -26
  100. package/dist/src/health/index.js.map +1 -0
  101. package/dist/src/index.d.ts +34 -23
  102. package/dist/src/index.d.ts.map +1 -0
  103. package/dist/src/index.js +40 -28
  104. package/dist/src/index.js.map +1 -0
  105. package/dist/src/mviProjection.d.ts +43 -6
  106. package/dist/src/mviProjection.d.ts.map +1 -0
  107. package/dist/src/mviProjection.js +32 -5
  108. package/dist/src/mviProjection.js.map +1 -0
  109. package/dist/src/native-loader.d.ts +49 -0
  110. package/dist/src/native-loader.d.ts.map +1 -0
  111. package/dist/src/native-loader.js +56 -0
  112. package/dist/src/native-loader.js.map +1 -0
  113. package/dist/src/problemDetails.d.ts +71 -4
  114. package/dist/src/problemDetails.d.ts.map +1 -0
  115. package/dist/src/problemDetails.js +27 -3
  116. package/dist/src/problemDetails.js.map +1 -0
  117. package/dist/src/shutdown/index.d.ts +103 -9
  118. package/dist/src/shutdown/index.d.ts.map +1 -0
  119. package/dist/src/shutdown/index.js +78 -12
  120. package/dist/src/shutdown/index.js.map +1 -0
  121. package/dist/src/tokenEstimator.d.ts +98 -11
  122. package/dist/src/tokenEstimator.d.ts.map +1 -0
  123. package/dist/src/tokenEstimator.js +91 -13
  124. package/dist/src/tokenEstimator.js.map +1 -0
  125. package/dist/src/types.d.ts +477 -11
  126. package/dist/src/types.d.ts.map +1 -0
  127. package/dist/src/types.js +76 -2
  128. package/dist/src/types.js.map +1 -0
  129. package/dist/src/validateEnvelope.d.ts +61 -2
  130. package/dist/src/validateEnvelope.d.ts.map +1 -0
  131. package/dist/src/validateEnvelope.js +81 -14
  132. package/dist/src/validateEnvelope.js.map +1 -0
  133. package/dist/tsconfig.build.tsbuildinfo +1 -0
  134. package/lafs.md +3 -4
  135. package/package.json +14 -12
  136. package/schemas/v1/agent-card.schema.json +0 -0
  137. package/schemas/v1/conformance-profiles.json +0 -0
  138. package/schemas/v1/context-ledger.schema.json +0 -0
  139. package/schemas/v1/discovery.schema.json +0 -0
  140. package/schemas/v1/envelope.schema.json +0 -0
  141. package/schemas/v1/error-registry.json +0 -0
  142. package/dist/src/mcpAdapter.d.ts +0 -28
  143. package/dist/src/mcpAdapter.js +0 -281
@@ -5,31 +5,64 @@
5
5
  * Uses the approximation: 1 token ≈ 4 characters.
6
6
  * Properly handles nested objects, arrays, Unicode graphemes, and circular references.
7
7
  */
8
+ /**
9
+ * Configuration options for the token estimator.
10
+ *
11
+ * @remarks
12
+ * All options have sensible defaults. Override individual fields to tune
13
+ * estimation accuracy or performance for specific workloads.
14
+ *
15
+ * @example
16
+ * ```typescript
17
+ * const opts: TokenEstimatorOptions = {
18
+ * charsPerToken: 3.5,
19
+ * maxDepth: 50,
20
+ * };
21
+ * ```
22
+ */
8
23
  export interface TokenEstimatorOptions {
9
24
  /**
10
- * Characters per token ratio (default: 4)
25
+ * Characters per token ratio.
26
+ * @defaultValue `4`
11
27
  */
12
28
  charsPerToken?: number;
13
29
  /**
14
- * Maximum depth to traverse for circular reference detection (default: 100)
30
+ * Maximum depth to traverse for circular reference detection.
31
+ * @defaultValue `100`
15
32
  */
16
33
  maxDepth?: number;
17
34
  /**
18
- * Maximum string length to process for Unicode grapheme counting (default: 100000)
35
+ * Maximum string length to process for Unicode grapheme counting.
36
+ * @defaultValue `100000`
19
37
  */
20
38
  maxStringLength?: number;
21
39
  }
22
40
  /**
23
- * TokenEstimator provides character-based token counting for JSON payloads.
41
+ * Character-based token estimator for JSON payloads.
24
42
  *
43
+ * @remarks
25
44
  * Algorithm:
26
- * 1. Serialize value to JSON (handling circular refs)
27
- * 2. Count Unicode graphemes (not bytes)
28
- * 3. Divide by charsPerToken ratio (default 4)
29
- * 4. Add overhead for structural characters
45
+ * 1. Recursively traverse the value (handling circular refs via WeakSet)
46
+ * 2. Count Unicode graphemes (not bytes) for string content
47
+ * 3. Divide by `charsPerToken` ratio (default 4)
48
+ * 4. Add overhead for structural JSON characters
49
+ *
50
+ * The estimator is intentionally conservative to avoid underestimating budget usage.
51
+ *
52
+ * @example
53
+ * ```typescript
54
+ * const estimator = new TokenEstimator({ charsPerToken: 4 });
55
+ * const tokens = estimator.estimate({ name: "hello", items: [1, 2, 3] });
56
+ * ```
30
57
  */
31
58
  export declare class TokenEstimator {
59
+ /** Resolved configuration with defaults applied */
32
60
  private options;
61
+ /**
62
+ * Create a new TokenEstimator.
63
+ *
64
+ * @param options - Configuration overrides (merged with defaults)
65
+ */
33
66
  constructor(options?: TokenEstimatorOptions);
34
67
  /**
35
68
  * Estimate tokens for any JavaScript value.
@@ -49,39 +82,93 @@ export declare class TokenEstimator {
49
82
  estimateJSON(json: string): number;
50
83
  /**
51
84
  * Internal recursive estimation with circular reference tracking.
85
+ *
86
+ * @param value - Value to estimate
87
+ * @param seen - WeakSet tracking visited objects for circular reference detection
88
+ * @param depth - Current recursion depth
89
+ * @returns Estimated token count for this value
52
90
  */
53
91
  private estimateWithTracking;
54
92
  /**
55
93
  * Estimate tokens for an array.
94
+ *
95
+ * @param arr - Array to estimate
96
+ * @param seen - WeakSet tracking visited objects
97
+ * @param depth - Current recursion depth
98
+ * @returns Estimated token count including brackets and separators
56
99
  */
57
100
  private estimateArray;
58
101
  /**
59
102
  * Estimate tokens for a plain object.
103
+ *
104
+ * @param obj - Object to estimate
105
+ * @param seen - WeakSet tracking visited objects
106
+ * @param depth - Current recursion depth
107
+ * @returns Estimated token count including braces, keys, colons, and separators
60
108
  */
61
109
  private estimateObject;
62
110
  /**
63
111
  * Check if a value can be safely serialized (no circular refs).
112
+ *
113
+ * @param value - Value to check
114
+ * @returns `true` if `JSON.stringify` succeeds without throwing
64
115
  */
65
116
  canSerialize(value: unknown): boolean;
66
117
  /**
67
- * Serialize value to JSON with circular reference handling.
68
- * Circular refs are replaced with "[Circular]".
118
+ * Serialize a value to JSON with circular reference handling.
119
+ *
120
+ * @param value - Value to serialize
121
+ * @returns JSON string with circular references replaced by `"[Circular]"`
69
122
  */
70
123
  safeStringify(value: unknown): string;
71
124
  /**
72
- * Create a safe copy of a value with circular refs removed.
125
+ * Create a deep copy of a value with circular refs replaced by `"[Circular]"`.
126
+ *
127
+ * @param value - Value to copy
128
+ * @returns Deep clone with all circular references replaced
73
129
  */
74
130
  safeCopy<T>(value: T): T;
75
131
  }
76
132
  /**
77
133
  * Global token estimator instance with default settings.
134
+ *
135
+ * @remarks
136
+ * Reuses a single estimator instance to avoid repeated object allocation.
137
+ * All default {@link TokenEstimatorOptions} values apply.
78
138
  */
79
139
  export declare const defaultEstimator: TokenEstimator;
80
140
  /**
81
141
  * Convenience function to estimate tokens for a value.
142
+ *
143
+ * @param value - Any JavaScript value to estimate
144
+ * @param options - Optional estimator configuration overrides
145
+ * @returns Estimated token count
146
+ *
147
+ * @remarks
148
+ * Uses the global {@link defaultEstimator} when no options are provided.
149
+ * Creates a new estimator instance when custom options are given.
150
+ *
151
+ * @example
152
+ * ```typescript
153
+ * const tokens = estimateTokens({ data: [1, 2, 3] });
154
+ * ```
82
155
  */
83
156
  export declare function estimateTokens(value: unknown, options?: TokenEstimatorOptions): number;
84
157
  /**
85
158
  * Convenience function to estimate tokens from a JSON string.
159
+ *
160
+ * @param json - Pre-serialized JSON string
161
+ * @param options - Optional estimator configuration overrides
162
+ * @returns Estimated token count
163
+ *
164
+ * @remarks
165
+ * More efficient than {@link estimateTokens} when you already have the
166
+ * JSON string, since it skips the serialization step.
167
+ *
168
+ * @example
169
+ * ```typescript
170
+ * const tokens = estimateTokensJSON('{"key": "value"}');
171
+ * ```
86
172
  */
87
173
  export declare function estimateTokensJSON(json: string, options?: TokenEstimatorOptions): number;
174
+ //# sourceMappingURL=tokenEstimator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokenEstimator.d.ts","sourceRoot":"","sources":["../../src/tokenEstimator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAqCD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IACzB,mDAAmD;IACnD,OAAO,CAAC,OAAO,CAAkC;IAEjD;;;;OAIG;gBACS,OAAO,GAAE,qBAA0B;IAI/C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAIhC;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQlC;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAiE5B;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAiBrB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAgCtB;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IASrC;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAcrC;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;CA+BzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,gBAAuB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAGtF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAGxF"}
@@ -6,22 +6,31 @@
6
6
  * Properly handles nested objects, arrays, Unicode graphemes, and circular references.
7
7
  */
8
8
  /**
9
- * Counts Unicode graphemes in a string using Intl.Segmenter when available.
10
- * Falls back to character counting for environments without Intl.Segmenter.
9
+ * Count Unicode graphemes in a string.
10
+ *
11
+ * @param str - Input string to count
12
+ * @returns Number of grapheme clusters in the string
13
+ *
14
+ * @remarks
15
+ * Uses `Intl.Segmenter` when available (Node.js 16+, modern browsers) for
16
+ * accurate grapheme counting. Falls back to spread-based code-point counting
17
+ * which handles surrogate pairs but not all grapheme clusters.
11
18
  */
12
19
  function countGraphemes(str) {
13
20
  // Use Intl.Segmenter for proper grapheme counting (Node.js 16+, modern browsers)
14
21
  if (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {
15
- // @ts-ignore - Intl.Segmenter may not be in all TypeScript lib versions
16
22
  const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
17
- // @ts-ignore
18
23
  return Array.from(segmenter.segment(str)).length;
19
24
  }
20
25
  // Fallback: count code points using spread operator (handles surrogate pairs)
21
26
  return [...str].length;
22
27
  }
23
28
  /**
24
- * Default options for token estimation
29
+ * Default options for token estimation.
30
+ *
31
+ * @remarks
32
+ * These values represent the baseline configuration used when no overrides
33
+ * are provided to the {@link TokenEstimator} constructor.
25
34
  */
26
35
  const DEFAULT_OPTIONS = {
27
36
  charsPerToken: 4,
@@ -29,16 +38,31 @@ const DEFAULT_OPTIONS = {
29
38
  maxStringLength: 100000,
30
39
  };
31
40
  /**
32
- * TokenEstimator provides character-based token counting for JSON payloads.
41
+ * Character-based token estimator for JSON payloads.
33
42
  *
43
+ * @remarks
34
44
  * Algorithm:
35
- * 1. Serialize value to JSON (handling circular refs)
36
- * 2. Count Unicode graphemes (not bytes)
37
- * 3. Divide by charsPerToken ratio (default 4)
38
- * 4. Add overhead for structural characters
45
+ * 1. Recursively traverse the value (handling circular refs via WeakSet)
46
+ * 2. Count Unicode graphemes (not bytes) for string content
47
+ * 3. Divide by `charsPerToken` ratio (default 4)
48
+ * 4. Add overhead for structural JSON characters
49
+ *
50
+ * The estimator is intentionally conservative to avoid underestimating budget usage.
51
+ *
52
+ * @example
53
+ * ```typescript
54
+ * const estimator = new TokenEstimator({ charsPerToken: 4 });
55
+ * const tokens = estimator.estimate({ name: "hello", items: [1, 2, 3] });
56
+ * ```
39
57
  */
40
58
  export class TokenEstimator {
59
+ /** Resolved configuration with defaults applied */
41
60
  options;
61
+ /**
62
+ * Create a new TokenEstimator.
63
+ *
64
+ * @param options - Configuration overrides (merged with defaults)
65
+ */
42
66
  constructor(options = {}) {
43
67
  this.options = { ...DEFAULT_OPTIONS, ...options };
44
68
  }
@@ -68,6 +92,11 @@ export class TokenEstimator {
68
92
  }
69
93
  /**
70
94
  * Internal recursive estimation with circular reference tracking.
95
+ *
96
+ * @param value - Value to estimate
97
+ * @param seen - WeakSet tracking visited objects for circular reference detection
98
+ * @param depth - Current recursion depth
99
+ * @returns Estimated token count for this value
71
100
  */
72
101
  estimateWithTracking(value, seen, depth) {
73
102
  // Prevent infinite recursion
@@ -124,6 +153,11 @@ export class TokenEstimator {
124
153
  }
125
154
  /**
126
155
  * Estimate tokens for an array.
156
+ *
157
+ * @param arr - Array to estimate
158
+ * @param seen - WeakSet tracking visited objects
159
+ * @param depth - Current recursion depth
160
+ * @returns Estimated token count including brackets and separators
127
161
  */
128
162
  estimateArray(arr, seen, depth) {
129
163
  let tokens = 1; // Opening bracket [ (already counted as structural)
@@ -139,6 +173,11 @@ export class TokenEstimator {
139
173
  }
140
174
  /**
141
175
  * Estimate tokens for a plain object.
176
+ *
177
+ * @param obj - Object to estimate
178
+ * @param seen - WeakSet tracking visited objects
179
+ * @param depth - Current recursion depth
180
+ * @returns Estimated token count including braces, keys, colons, and separators
142
181
  */
143
182
  estimateObject(obj, seen, depth) {
144
183
  let tokens = 1; // Opening brace {
@@ -162,6 +201,9 @@ export class TokenEstimator {
162
201
  }
163
202
  /**
164
203
  * Check if a value can be safely serialized (no circular refs).
204
+ *
205
+ * @param value - Value to check
206
+ * @returns `true` if `JSON.stringify` succeeds without throwing
165
207
  */
166
208
  canSerialize(value) {
167
209
  try {
@@ -173,8 +215,10 @@ export class TokenEstimator {
173
215
  }
174
216
  }
175
217
  /**
176
- * Serialize value to JSON with circular reference handling.
177
- * Circular refs are replaced with "[Circular]".
218
+ * Serialize a value to JSON with circular reference handling.
219
+ *
220
+ * @param value - Value to serialize
221
+ * @returns JSON string with circular references replaced by `"[Circular]"`
178
222
  */
179
223
  safeStringify(value) {
180
224
  const seen = new WeakSet();
@@ -189,7 +233,10 @@ export class TokenEstimator {
189
233
  });
190
234
  }
191
235
  /**
192
- * Create a safe copy of a value with circular refs removed.
236
+ * Create a deep copy of a value with circular refs replaced by `"[Circular]"`.
237
+ *
238
+ * @param value - Value to copy
239
+ * @returns Deep clone with all circular references replaced
193
240
  */
194
241
  safeCopy(value) {
195
242
  const seen = new WeakSet();
@@ -220,10 +267,27 @@ export class TokenEstimator {
220
267
  }
221
268
  /**
222
269
  * Global token estimator instance with default settings.
270
+ *
271
+ * @remarks
272
+ * Reuses a single estimator instance to avoid repeated object allocation.
273
+ * All default {@link TokenEstimatorOptions} values apply.
223
274
  */
224
275
  export const defaultEstimator = new TokenEstimator();
225
276
  /**
226
277
  * Convenience function to estimate tokens for a value.
278
+ *
279
+ * @param value - Any JavaScript value to estimate
280
+ * @param options - Optional estimator configuration overrides
281
+ * @returns Estimated token count
282
+ *
283
+ * @remarks
284
+ * Uses the global {@link defaultEstimator} when no options are provided.
285
+ * Creates a new estimator instance when custom options are given.
286
+ *
287
+ * @example
288
+ * ```typescript
289
+ * const tokens = estimateTokens({ data: [1, 2, 3] });
290
+ * ```
227
291
  */
228
292
  export function estimateTokens(value, options) {
229
293
  const estimator = options ? new TokenEstimator(options) : defaultEstimator;
@@ -231,8 +295,22 @@ export function estimateTokens(value, options) {
231
295
  }
232
296
  /**
233
297
  * Convenience function to estimate tokens from a JSON string.
298
+ *
299
+ * @param json - Pre-serialized JSON string
300
+ * @param options - Optional estimator configuration overrides
301
+ * @returns Estimated token count
302
+ *
303
+ * @remarks
304
+ * More efficient than {@link estimateTokens} when you already have the
305
+ * JSON string, since it skips the serialization step.
306
+ *
307
+ * @example
308
+ * ```typescript
309
+ * const tokens = estimateTokensJSON('{"key": "value"}');
310
+ * ```
234
311
  */
235
312
  export function estimateTokensJSON(json, options) {
236
313
  const estimator = options ? new TokenEstimator(options) : defaultEstimator;
237
314
  return estimator.estimateJSON(json);
238
315
  }
316
+ //# sourceMappingURL=tokenEstimator.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokenEstimator.js","sourceRoot":"","sources":["../../src/tokenEstimator.ts"],"names":[],"mappings":"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"}