maka-agent 0.2.0-dev.30.20260912 → 0.2.0-dev.31.20260913

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 (194) hide show
  1. package/THIRD_PARTY_NOTICES.txt +392 -0
  2. package/dist/acp/maka-acp-agent.js +8 -2
  3. package/dist/acp/prompt-content.js +225 -0
  4. package/dist/acp/session-event-mapper.js +103 -0
  5. package/dist/acp/session-registry.js +654 -17
  6. package/dist/acp/stdio-server.js +10 -1
  7. package/dist/cli-core.js +1 -1
  8. package/dist/pi-transcript-tools.js +3 -2
  9. package/dist/pi-transcript.js +12 -2
  10. package/dist/runtime-host-session-channel.js +63 -9
  11. package/native/runtime-host-windows-task-launcher/prebuilds/win32-x64/maka-runtime-host-task-launcher.exe +0 -0
  12. package/node_modules/@maka/core/dist/artifacts.js +6 -0
  13. package/node_modules/@maka/core/dist/attachments.js +7 -2
  14. package/node_modules/@maka/core/dist/durable-tool-result-projection.js +3 -1
  15. package/node_modules/@maka/core/dist/events.js +21 -0
  16. package/node_modules/@maka/core/dist/goal.js +44 -2
  17. package/node_modules/@maka/core/dist/permission.js +0 -1
  18. package/node_modules/@maka/core/dist/runtime-boundary.js +73 -29
  19. package/node_modules/@maka/core/dist/runtime-event.js +6 -3
  20. package/node_modules/@maka/core/dist/runtime-handoff.js +10 -2
  21. package/node_modules/@maka/core/dist/runtime-logical-execution.js +39 -14
  22. package/node_modules/@maka/core/dist/tool-result-archive-evidence.js +3 -1
  23. package/node_modules/@maka/core/dist/tool-result-record-schema.js +2 -1
  24. package/node_modules/@maka/core/dist/unified-diff.js +33 -26
  25. package/node_modules/@maka/runtime/dist/ai-sdk-compaction.js +49 -178
  26. package/node_modules/@maka/runtime/dist/ai-sdk-message-projection.js +7 -2
  27. package/node_modules/@maka/runtime/dist/ai-sdk-turn.js +15 -53
  28. package/node_modules/@maka/runtime/dist/bash-model-output.js +7 -1
  29. package/node_modules/@maka/runtime/dist/bash-tail-buffer.js +13 -52
  30. package/node_modules/@maka/runtime/dist/builtin-tools.js +59 -111
  31. package/node_modules/@maka/runtime/dist/child-fd-input.js +3 -2
  32. package/node_modules/@maka/runtime/dist/context-budget-policy.js +1 -11
  33. package/node_modules/@maka/runtime/dist/context-budget.js +12 -1
  34. package/node_modules/@maka/runtime/dist/conversation-copy.js +104 -9
  35. package/node_modules/@maka/runtime/dist/filesystem-executor.js +10 -6
  36. package/node_modules/@maka/runtime/dist/filesystem-worker/client.js +77 -19
  37. package/node_modules/@maka/runtime/dist/filesystem-worker/launch-spec.js +66 -55
  38. package/node_modules/@maka/runtime/dist/filesystem-worker/operations.js +34 -97
  39. package/node_modules/@maka/runtime/dist/filesystem-worker/protocol.js +25 -10
  40. package/node_modules/@maka/runtime/dist/filesystem-worker/worker-entry.js +2 -0
  41. package/node_modules/@maka/runtime/dist/glob-search.js +74 -0
  42. package/node_modules/@maka/runtime/dist/goal-continuation.js +78 -8
  43. package/node_modules/@maka/runtime/dist/goal-state.js +7 -0
  44. package/node_modules/@maka/runtime/dist/grep-search.js +155 -0
  45. package/node_modules/@maka/runtime/dist/ledger-tool-result-archive-reader.js +84 -94
  46. package/node_modules/@maka/runtime/dist/model-history.js +25 -3
  47. package/node_modules/@maka/runtime/dist/pipe-tail-collector.js +6 -9
  48. package/node_modules/@maka/runtime/dist/read-page.js +231 -0
  49. package/node_modules/@maka/runtime/dist/request-projection.js +2 -15
  50. package/node_modules/@maka/runtime/dist/ripgrep-executable.js +62 -0
  51. package/node_modules/@maka/runtime/dist/ripgrep-guidance.js +81 -0
  52. package/node_modules/@maka/runtime/dist/runtime-event-read-model.js +187 -20
  53. package/node_modules/@maka/runtime/dist/runtime-read-model.js +2 -1
  54. package/node_modules/@maka/runtime/dist/sandbox/linux-profile-path.js +7 -1
  55. package/node_modules/@maka/runtime/dist/sandbox/linux-sandbox.js +20 -5
  56. package/node_modules/@maka/runtime/dist/session-manager.js +6 -6
  57. package/node_modules/@maka/runtime/dist/session-recap.js +9 -5
  58. package/node_modules/@maka/runtime/dist/shell-exec.js +7 -25
  59. package/node_modules/@maka/runtime/dist/shell-run-manager.js +1 -1
  60. package/node_modules/@maka/runtime/dist/shell-run-tool-result.js +1 -1
  61. package/node_modules/@maka/runtime/dist/shell-tools.js +6 -12
  62. package/node_modules/@maka/runtime/dist/tool-availability.js +0 -1
  63. package/node_modules/@maka/runtime/dist/tool-output.js +1 -1
  64. package/node_modules/@maka/runtime/dist/tool-result-archive-capability.js +24 -36
  65. package/node_modules/@maka/runtime/dist/tool-result-archive-resource.js +32 -527
  66. package/node_modules/@maka/runtime/dist/tool-result-archive-transition.js +17 -119
  67. package/node_modules/@maka/runtime/dist/tool-result-archive.js +7 -25
  68. package/node_modules/@maka/runtime/dist/tool-runtime.js +7 -5
  69. package/node_modules/@maka/runtime/dist/workers/filesystem-worker.js +6933 -3681
  70. package/node_modules/@maka/runtime/dist/workspace-executor.js +20 -24
  71. package/node_modules/@maka/runtime/package.json +2 -0
  72. package/node_modules/@maka/runtime-host/dist/client/host-handoff-copy.js +185 -191
  73. package/node_modules/@maka/runtime-host/dist/client/reconnecting-connection.js +3 -0
  74. package/node_modules/@maka/runtime-host/dist/protocol/index.js +5 -1
  75. package/node_modules/@maka/runtime-host/dist/protocol/message.js +2 -2
  76. package/node_modules/@maka/runtime-host/dist/protocol/operations.js +1 -0
  77. package/node_modules/@maka/runtime-host/dist/protocol/session-continuity.js +2 -2
  78. package/node_modules/@maka/runtime-host/dist/protocol/turn.js +10 -2
  79. package/node_modules/@maka/runtime-host/dist/protocol/workhub-coordination.js +38 -0
  80. package/node_modules/@maka/runtime-host/dist/server/execution-artifacts.js +2 -8
  81. package/node_modules/@maka/runtime-host/dist/server/execution-composition.js +2 -0
  82. package/node_modules/@maka/runtime-host/dist/server/goal-coordinator.js +81 -7
  83. package/node_modules/@maka/runtime-host/dist/server/hosted-execution-tool-profile.js +13 -13
  84. package/node_modules/@maka/runtime-host/dist/server/interaction-coordinator.js +65 -0
  85. package/node_modules/@maka/runtime-host/dist/server/root-turn-coordinator.js +1 -0
  86. package/node_modules/@maka/runtime-host/dist/server/session-continuity-coordinator.js +5 -2
  87. package/node_modules/@maka/runtime-host/dist/server/session-transcript-reader.js +88 -72
  88. package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-action-gate.js +21 -4
  89. package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-coordinator.js +145 -1
  90. package/node_modules/@maka/storage/dist/agent-run-store.js +5 -2
  91. package/node_modules/@maka/storage/dist/execution-stores.js +2 -1
  92. package/node_modules/@maka/storage/dist/runtime-transcript-query.js +27 -14
  93. package/node_modules/@maka/storage/dist/sqlite-runtime-store.js +69 -3
  94. package/node_modules/balanced-match/LICENSE.md +23 -0
  95. package/node_modules/balanced-match/README.md +57 -0
  96. package/node_modules/balanced-match/dist/commonjs/index.js +59 -0
  97. package/node_modules/balanced-match/dist/commonjs/package.json +3 -0
  98. package/node_modules/balanced-match/dist/esm/index.js +54 -0
  99. package/node_modules/balanced-match/dist/esm/package.json +3 -0
  100. package/node_modules/balanced-match/package.json +68 -0
  101. package/node_modules/brace-expansion/LICENSE +23 -0
  102. package/node_modules/brace-expansion/README.md +105 -0
  103. package/node_modules/brace-expansion/dist/commonjs/index.js +289 -0
  104. package/node_modules/brace-expansion/dist/commonjs/package.json +3 -0
  105. package/node_modules/brace-expansion/dist/esm/index.js +285 -0
  106. package/node_modules/brace-expansion/dist/esm/package.json +3 -0
  107. package/node_modules/brace-expansion/package.json +64 -0
  108. package/node_modules/glob/LICENSE.md +63 -0
  109. package/node_modules/glob/README.md +1203 -0
  110. package/node_modules/glob/dist/commonjs/glob.js +248 -0
  111. package/node_modules/glob/dist/commonjs/has-magic.js +27 -0
  112. package/node_modules/glob/dist/commonjs/ignore.js +119 -0
  113. package/node_modules/glob/dist/commonjs/index.js +68 -0
  114. package/node_modules/glob/dist/commonjs/index.min.js +4 -0
  115. package/node_modules/glob/dist/commonjs/package.json +3 -0
  116. package/node_modules/glob/dist/commonjs/pattern.js +223 -0
  117. package/node_modules/glob/dist/commonjs/processor.js +301 -0
  118. package/node_modules/glob/dist/commonjs/walker.js +387 -0
  119. package/node_modules/glob/dist/esm/glob.js +244 -0
  120. package/node_modules/glob/dist/esm/has-magic.js +23 -0
  121. package/node_modules/glob/dist/esm/ignore.js +115 -0
  122. package/node_modules/glob/dist/esm/index.js +55 -0
  123. package/node_modules/glob/dist/esm/index.min.js +4 -0
  124. package/node_modules/glob/dist/esm/package.json +3 -0
  125. package/node_modules/glob/dist/esm/pattern.js +219 -0
  126. package/node_modules/glob/dist/esm/processor.js +294 -0
  127. package/node_modules/glob/dist/esm/walker.js +381 -0
  128. package/node_modules/glob/package.json +98 -0
  129. package/node_modules/minimatch/LICENSE.md +55 -0
  130. package/node_modules/minimatch/README.md +528 -0
  131. package/node_modules/minimatch/dist/commonjs/assert-valid-pattern.js +14 -0
  132. package/node_modules/minimatch/dist/commonjs/ast.js +845 -0
  133. package/node_modules/minimatch/dist/commonjs/brace-expressions.js +150 -0
  134. package/node_modules/minimatch/dist/commonjs/escape.js +30 -0
  135. package/node_modules/minimatch/dist/commonjs/index.js +1127 -0
  136. package/node_modules/minimatch/dist/commonjs/package.json +3 -0
  137. package/node_modules/minimatch/dist/commonjs/unescape.js +38 -0
  138. package/node_modules/minimatch/dist/esm/assert-valid-pattern.js +10 -0
  139. package/node_modules/minimatch/dist/esm/ast.js +841 -0
  140. package/node_modules/minimatch/dist/esm/brace-expressions.js +146 -0
  141. package/node_modules/minimatch/dist/esm/escape.js +26 -0
  142. package/node_modules/minimatch/dist/esm/index.js +1114 -0
  143. package/node_modules/minimatch/dist/esm/package.json +3 -0
  144. package/node_modules/minimatch/dist/esm/unescape.js +34 -0
  145. package/node_modules/minimatch/package.json +73 -0
  146. package/node_modules/minipass/LICENSE.md +55 -0
  147. package/node_modules/minipass/README.md +825 -0
  148. package/node_modules/minipass/dist/commonjs/index.js +1038 -0
  149. package/node_modules/minipass/dist/commonjs/package.json +3 -0
  150. package/node_modules/minipass/dist/esm/index.js +1020 -0
  151. package/node_modules/minipass/dist/esm/package.json +3 -0
  152. package/node_modules/minipass/package.json +77 -0
  153. package/node_modules/path-scurry/LICENSE.md +55 -0
  154. package/node_modules/path-scurry/README.md +636 -0
  155. package/node_modules/path-scurry/dist/commonjs/index.js +2018 -0
  156. package/node_modules/path-scurry/dist/commonjs/package.json +3 -0
  157. package/node_modules/path-scurry/dist/esm/index.js +1983 -0
  158. package/node_modules/path-scurry/dist/esm/package.json +3 -0
  159. package/node_modules/path-scurry/node_modules/lru-cache/LICENSE.md +55 -0
  160. package/node_modules/path-scurry/node_modules/lru-cache/README.md +469 -0
  161. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/browser/diagnostics-channel.js +7 -0
  162. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/browser/index.js +1726 -0
  163. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/browser/index.min.js +2 -0
  164. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/browser/perf.js +10 -0
  165. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/diagnostics-channel-cjs.d.cts.map +1 -0
  166. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/diagnostics-channel.js +7 -0
  167. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/index.js +1726 -0
  168. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/index.min.js +2 -0
  169. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/node/diagnostics-channel.js +9 -0
  170. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/node/index.js +1726 -0
  171. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/node/index.min.js +2 -0
  172. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/node/perf.js +10 -0
  173. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/package.json +3 -0
  174. package/node_modules/path-scurry/node_modules/lru-cache/dist/commonjs/perf.js +10 -0
  175. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/browser/diagnostics-channel.js +4 -0
  176. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/browser/index.js +1722 -0
  177. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/browser/index.min.js +2 -0
  178. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/browser/perf.js +7 -0
  179. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/diagnostics-channel-esm.d.mts.map +1 -0
  180. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/diagnostics-channel.js +19 -0
  181. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/index.js +1722 -0
  182. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/index.min.js +2 -0
  183. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/node/diagnostics-channel.js +6 -0
  184. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/node/index.js +1722 -0
  185. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/node/index.min.js +2 -0
  186. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/node/perf.js +7 -0
  187. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/package.json +3 -0
  188. package/node_modules/path-scurry/node_modules/lru-cache/dist/esm/perf.js +7 -0
  189. package/node_modules/path-scurry/node_modules/lru-cache/package.json +154 -0
  190. package/node_modules/path-scurry/package.json +72 -0
  191. package/package.json +1 -1
  192. package/node_modules/@maka/runtime/dist/active-tool-result-prune.js +0 -248
  193. package/node_modules/@maka/runtime/dist/active-tool-result-working-set.js +0 -218
  194. package/node_modules/@maka/runtime/dist/archive-read-tool.js +0 -115
@@ -0,0 +1,3 @@
1
+ {
2
+ "type": "module"
3
+ }
@@ -0,0 +1,55 @@
1
+ # Blue Oak Model License
2
+
3
+ Version 1.0.0
4
+
5
+ ## Purpose
6
+
7
+ This license gives everyone as much permission to work with
8
+ this software as possible, while protecting contributors
9
+ from liability.
10
+
11
+ ## Acceptance
12
+
13
+ In order to receive this license, you must agree to its
14
+ rules. The rules of this license are both obligations
15
+ under that agreement and conditions to your license.
16
+ You must not do anything with this software that triggers
17
+ a rule that you cannot or will not follow.
18
+
19
+ ## Copyright
20
+
21
+ Each contributor licenses you to do everything with this
22
+ software that would otherwise infringe that contributor's
23
+ copyright in it.
24
+
25
+ ## Notices
26
+
27
+ You must ensure that everyone who gets a copy of
28
+ any part of this software from you, with or without
29
+ changes, also gets the text of this license or a link to
30
+ <https://blueoakcouncil.org/license/1.0.0>.
31
+
32
+ ## Excuse
33
+
34
+ If anyone notifies you in writing that you have not
35
+ complied with [Notices](#notices), you can keep your
36
+ license by taking all practical steps to comply within 30
37
+ days after the notice. If you do not do so, your license
38
+ ends immediately.
39
+
40
+ ## Patent
41
+
42
+ Each contributor licenses you to do everything with this
43
+ software that would otherwise infringe any patent claims
44
+ they can license or become able to license.
45
+
46
+ ## Reliability
47
+
48
+ No contributor can revoke this license.
49
+
50
+ ## No Liability
51
+
52
+ ***As far as the law allows, this software comes as is,
53
+ without any warranty or condition, and no contributor
54
+ will be liable to anyone for any damages related to this
55
+ software or this license, under any kind of legal claim.***
@@ -0,0 +1,469 @@
1
+ # lru-cache
2
+
3
+ A cache object that deletes the least-recently-used items.
4
+
5
+ Specify a max number of the most recently used items that you
6
+ want to keep, and this cache will keep that many of the most
7
+ recently accessed items.
8
+
9
+ This is not primarily a TTL cache, and does not make strong TTL
10
+ guarantees. There is no preemptive pruning of expired items by
11
+ default, but you _may_ set a TTL on the cache or on a single
12
+ `set`. If you do so, it will treat expired items as missing, and
13
+ delete them when fetched. If you are more interested in TTL
14
+ caching than LRU caching, check out
15
+ [@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
16
+
17
+ As of version 7, this is one of the most performant LRU
18
+ implementations available in JavaScript, and supports a wide
19
+ diversity of use cases. However, note that using some of the
20
+ features will necessarily impact performance, by causing the
21
+ cache to have to do more work. See the "Performance" section
22
+ below.
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ npm install lru-cache --save
28
+ ```
29
+
30
+ ## Usage
31
+
32
+ ```js
33
+ // hybrid module, either works
34
+ import { LRUCache } from 'lru-cache'
35
+ // or:
36
+ const { LRUCache } = require('lru-cache')
37
+ // or in minified form for web browsers:
38
+ import { LRUCache } from 'http://unpkg.com/lru-cache@9/dist/mjs/index.min.mjs'
39
+
40
+ // At least one of 'max', 'ttl', or 'maxSize' is required, to prevent
41
+ // unsafe unbounded storage.
42
+ //
43
+ // In most cases, it's best to specify a max for performance, so all
44
+ // the required memory allocation is done up-front.
45
+ //
46
+ // All the other options are optional, see the sections below for
47
+ // documentation on what each one does. Most of them can be
48
+ // overridden for specific items in get()/set()
49
+ const options = {
50
+ max: 500,
51
+
52
+ // for use with tracking overall storage size
53
+ maxSize: 5000,
54
+ sizeCalculation: (value, key) => {
55
+ return 1
56
+ },
57
+
58
+ // for use when you need to clean up something when objects
59
+ // are evicted from the cache
60
+ dispose: (value, key, reason) => {
61
+ freeFromMemoryOrWhatever(value)
62
+ },
63
+
64
+ // for use when you need to know that an item is being inserted
65
+ // note that this does NOT allow you to prevent the insertion,
66
+ // it just allows you to know about it.
67
+ onInsert: (value, key, reason) => {
68
+ logInsertionOrWhatever(key, value)
69
+ },
70
+
71
+ // how long to live in ms
72
+ ttl: 1000 * 60 * 5,
73
+
74
+ // return stale items before removing from cache?
75
+ allowStale: false,
76
+
77
+ updateAgeOnGet: false,
78
+ updateAgeOnHas: false,
79
+
80
+ // async method to use for cache.fetch(), for
81
+ // stale-while-revalidate type of behavior
82
+ fetchMethod: async (key, staleValue, { options, signal, context }) => {},
83
+ }
84
+
85
+ const cache = new LRUCache(options)
86
+
87
+ cache.set('key', 'value')
88
+ cache.get('key') // "value"
89
+
90
+ // non-string keys ARE fully supported
91
+ // but note that it must be THE SAME object, not
92
+ // just a JSON-equivalent object.
93
+ var someObject = { a: 1 }
94
+ cache.set(someObject, 'a value')
95
+ // Object keys are not toString()-ed
96
+ cache.set('[object Object]', 'a different value')
97
+ assert.equal(cache.get(someObject), 'a value')
98
+ // A similar object with same keys/values won't work,
99
+ // because it's a different object identity
100
+ assert.equal(cache.get({ a: 1 }), undefined)
101
+
102
+ cache.clear() // empty the cache
103
+ ```
104
+
105
+ If you put more stuff in the cache, then less recently used items
106
+ will fall out. That's what an LRU cache is.
107
+
108
+ For full description of the API and all options, please see [the
109
+ LRUCache typedocs](https://isaacs.github.io/node-lru-cache/)
110
+
111
+ ## Storage Bounds Safety
112
+
113
+ This implementation aims to be as flexible as possible, within
114
+ the limits of safe memory consumption and optimal performance.
115
+
116
+ At initial object creation, storage is allocated for `max` items.
117
+ If `max` is set to zero, then some performance is lost, and item
118
+ count is unbounded. Either `maxSize` or `ttl` _must_ be set if
119
+ `max` is not specified.
120
+
121
+ If `maxSize` is set, then this creates a safe limit on the
122
+ maximum storage consumed, but without the performance benefits of
123
+ pre-allocation. When `maxSize` is set, every item _must_ provide
124
+ a size, either via the `sizeCalculation` method provided to the
125
+ constructor, or via a `size` or `sizeCalculation` option provided
126
+ to `cache.set()`. The size of every item _must_ be a positive
127
+ integer.
128
+
129
+ If neither `max` nor `maxSize` are set, then `ttl` tracking must
130
+ be enabled. Note that, even when tracking item `ttl`, items are
131
+ _not_ preemptively deleted when they become stale, unless
132
+ `ttlAutopurge` is enabled. Instead, they are only purged the
133
+ next time the key is requested. Thus, if `ttlAutopurge`, `max`,
134
+ and `maxSize` are all not set, then the cache will potentially
135
+ grow unbounded.
136
+
137
+ In this case, a warning is printed to standard error. Future
138
+ versions may require the use of `ttlAutopurge` if `max` and
139
+ `maxSize` are not specified.
140
+
141
+ If you truly wish to use a cache that is bound _only_ by TTL
142
+ expiration, consider using a `Map` object, and calling
143
+ `setTimeout` to delete entries when they expire. It will perform
144
+ much better than an LRU cache.
145
+
146
+ Here is an implementation you may use, under the same
147
+ [license](./LICENSE) as this package:
148
+
149
+ ```js
150
+ // a storage-unbounded ttl cache that is not an lru-cache
151
+ const cache = {
152
+ data: new Map(),
153
+ timers: new Map(),
154
+ set: (k, v, ttl) => {
155
+ if (cache.timers.has(k)) {
156
+ clearTimeout(cache.timers.get(k))
157
+ }
158
+ cache.timers.set(
159
+ k,
160
+ setTimeout(() => cache.delete(k), ttl),
161
+ )
162
+ cache.data.set(k, v)
163
+ },
164
+ get: k => cache.data.get(k),
165
+ has: k => cache.data.has(k),
166
+ delete: k => {
167
+ if (cache.timers.has(k)) {
168
+ clearTimeout(cache.timers.get(k))
169
+ }
170
+ cache.timers.delete(k)
171
+ return cache.data.delete(k)
172
+ },
173
+ clear: () => {
174
+ cache.data.clear()
175
+ for (const v of cache.timers.values()) {
176
+ clearTimeout(v)
177
+ }
178
+ cache.timers.clear()
179
+ },
180
+ }
181
+ ```
182
+
183
+ If that isn't to your liking, check out
184
+ [@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
185
+
186
+ ## Storing Undefined Values
187
+
188
+ This cache never stores undefined values, as `undefined` is used
189
+ internally in a few places to indicate that a key is not in the
190
+ cache.
191
+
192
+ You may call `cache.set(key, undefined)`, but this is just
193
+ an alias for `cache.delete(key)`. Note that this has the effect
194
+ that `cache.has(key)` will return _false_ after setting it to
195
+ undefined.
196
+
197
+ ```js
198
+ cache.set(myKey, undefined)
199
+ cache.has(myKey) // false!
200
+ ```
201
+
202
+ If you need to track `undefined` values, and still note that the
203
+ key is in the cache, an easy workaround is to use a sigil object
204
+ of your own.
205
+
206
+ ```js
207
+ import { LRUCache } from 'lru-cache'
208
+ const undefinedValue = Symbol('undefined')
209
+ const cache = new LRUCache(...)
210
+ const mySet = (key, value) =>
211
+ cache.set(key, value === undefined ? undefinedValue : value)
212
+ const myGet = (key, value) => {
213
+ const v = cache.get(key)
214
+ return v === undefinedValue ? undefined : v
215
+ }
216
+ ```
217
+
218
+ ## Tracing and Observability
219
+
220
+ Most methods can accept a `status` option, which is an
221
+ [`LRUCache.Status`](https://isaacs.github.io/node-lru-cache/interfaces/LRUCache.LRUCache.Status.html)
222
+ object that will be decorated along the operation with
223
+ indications about what was done and why.
224
+
225
+ Additionally, this library is instrumented using the
226
+ [`node:diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html)
227
+ module on Node and other platforms that support it. In order to
228
+ get diagnostics metrics, listen on the
229
+ `channel('lru-cache:metrics')`. To get Tracing Channel traces,
230
+ subscribe to the `tracingChannel('lru-cache')`. The
231
+ [`LRUCache.Status`](https://isaacs.github.io/node-lru-cache/interfaces/LRUCache.LRUCache.Status.html)
232
+ objects will be provided as the message context to those channel
233
+ listeners.
234
+
235
+ For example, you could do the following to get comprehensive
236
+ information about every LRUCache instance in your application:
237
+
238
+ ```ts
239
+ import { tracingChannel, subscribe } from 'node:diagnostics_channel'
240
+
241
+ subscribe('lru-cache:metrics', (message, name) => {
242
+ // name will always be 'lru-cache:metrics'
243
+ // message will be the LRUCache.Status object for whatever
244
+ // synchronous operation was performed.
245
+ console.error('LRUCache Metrics', message)
246
+ })
247
+
248
+ tracingChannel('lru-cache').subscribe({
249
+ start: status => {
250
+ // a traced operation is starting
251
+ },
252
+ asyncStart: status => {
253
+ // an async traced operation is starting
254
+ },
255
+ asyncEnd: status => {
256
+ // an async traced operation is ending
257
+ }
258
+ error: status => {
259
+ // a traced operation failed
260
+ },
261
+ end: status => {
262
+ // a traced operation is complete
263
+ },
264
+ })
265
+ ```
266
+
267
+ The async `cache.fetch()` and `cache.forceFetch` methods are
268
+ covered by `tracingChannels`. All the other operations are
269
+ covered by the `lru-cache:metrics` channel, because they are
270
+ strictly synchronous, and thus don't have an asynchronous
271
+ lifecycle to track.
272
+
273
+ Note that using `status` objects or using
274
+ `node:diagnostics_channel` listeners _will_ impose a modest
275
+ performance penalty. Creating data objects is not ever free; do
276
+ not believe anyone who tells you otherwise. But it is as small as
277
+ possible.
278
+
279
+ ### Platform Compatibility Caveat
280
+
281
+ Not all platforms support the `node:diagnostics_channel` module.
282
+ Currently, this is only available in Node, Bun, and Deno, and
283
+ some edge computing platforms that provide a Node compatibility
284
+ layer.
285
+
286
+ To work around this, if you are loading in a non-Node
287
+ environment, the package.json exports will direct your module
288
+ loader to pull in a version that starts out with a dummy
289
+ implementation, then does a conditional dynamic `import` of the
290
+ `node:diagnostics_channel` module, and then swaps out those
291
+ dummy objects with the real thing if it succeeds. This means that
292
+ cache metrics and tracing channels started in the first load-time
293
+ tick of your application will _not_ be covered, except in
294
+ environments that load using the `require` import
295
+ condition, or both the `node` and `esm` import conditions
296
+ together.
297
+
298
+ Top-level await _could_ be used to remove this caveat, but that
299
+ feature is dead on arrival, unfortunately. See
300
+ [#397](https://github.com/isaacs/node-lru-cache/issues/397) and
301
+ [#398](https://github.com/isaacs/node-lru-cache/issues/398) for
302
+ more details.
303
+
304
+ ## Performance
305
+
306
+ As of April 2026, version 11 of this library is one of the most
307
+ performant LRU cache implementations in JavaScript.
308
+
309
+ Benchmarks can be extremely difficult to get right. In
310
+ particular, the performance of set/get/delete operations on
311
+ objects will vary _wildly_ depending on the type of key used. V8
312
+ is highly optimized for objects with keys that are short strings,
313
+ especially integer numeric strings. Thus any benchmark which
314
+ tests _solely_ using numbers as keys will tend to find that an
315
+ object-based approach performs the best.
316
+
317
+ Note that coercing _anything_ to strings to use as object keys is
318
+ unsafe, unless you can be 100% certain that no other type of
319
+ value will be used. For example:
320
+
321
+ ```js
322
+ const myCache = {}
323
+ const set = (k, v) => (myCache[k] = v)
324
+ const get = k => myCache[k]
325
+
326
+ set({}, 'please hang onto this for me')
327
+ set('[object Object]', 'oopsie')
328
+ ```
329
+
330
+ Also beware of "Just So" stories regarding performance. Garbage
331
+ collection of large (especially: deep) object graphs can be
332
+ incredibly costly, with several "tipping points" where it
333
+ increases exponentially. As a result, putting that off until
334
+ later can make it much worse, and less predictable. If a library
335
+ performs well, but only in a scenario where the object graph is
336
+ kept shallow, then that won't help you if you are using large
337
+ objects as keys.
338
+
339
+ In general, when attempting to use a library to improve
340
+ performance (such as a cache like this one), it's best to choose
341
+ an option that will perform well in the sorts of scenarios where
342
+ you'll actually use it.
343
+
344
+ This library is optimized for repeated gets and minimizing
345
+ eviction time, since that is the expected need of a LRU. Set
346
+ operations are somewhat slower on average than a few other
347
+ options, in part because of that optimization. It is assumed
348
+ that you'll be caching some costly operation, ideally as rarely
349
+ as possible, so optimizing set over get would be unwise.
350
+
351
+ If performance matters to you:
352
+
353
+ 1. If it's at all possible to use small integer values as keys,
354
+ and you can guarantee that no other types of values will be
355
+ used as keys, then do that, and use a cache such as
356
+ [lru-fast](https://npmjs.com/package/lru-fast), or
357
+ [mnemonist's
358
+ LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache)
359
+ which uses an Object as its data store.
360
+
361
+ 2. Failing that, if you can use short non-numeric strings (ie,
362
+ less than 256 characters) as your keys, and you do not need
363
+ any of the other features of this library, use [mnemonist's
364
+ LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache).
365
+
366
+ 3. If the types of your keys will be anything else, especially
367
+ long strings, strings that look like floats, objects, or some
368
+ mix of types, or if you aren't sure, then this library will
369
+ work well for you.
370
+
371
+ If you do not need the features that this library provides
372
+ (like asynchronous fetching, a variety of TTL staleness
373
+ options, and so on), then [mnemonist's
374
+ LRUMap](https://yomguithereal.github.io/mnemonist/lru-map) is
375
+ also a very good option, and just slightly faster than this
376
+ module (since it does considerably less).
377
+
378
+ 4. Do not use a `dispose` function, size tracking, or especially
379
+ ttl behavior or observability features, unless absolutely
380
+ needed. These features are convenient, and necessary in some
381
+ use cases, and every attempt has been made to make the
382
+ performance impact minimal, but it isn't nothing.
383
+
384
+ ## Testing
385
+
386
+ When writing tests that involve TTL-related functionality, note
387
+ that this module creates an internal reference to the global
388
+ `performance` or `Date` objects at import time. If you import it
389
+ statically at the top level, those references cannot be mocked or
390
+ overridden in your test environment.
391
+
392
+ To avoid this, dynamically import the package within your tests
393
+ so that the references are captured after your mocks are applied.
394
+ For example:
395
+
396
+ ```ts
397
+ // ❌ Not recommended
398
+ import { LRUCache } from 'lru-cache'
399
+ // mocking timers, e.g. jest.useFakeTimers()
400
+
401
+ // ✅ Recommended for TTL tests
402
+ // mocking timers, e.g. jest.useFakeTimers()
403
+ const { LRUCache } = await import('lru-cache')
404
+ ```
405
+
406
+ This ensures that your mocked timers or time sources are
407
+ respected when testing TTL behavior.
408
+
409
+ Additionally, you can pass in a `perf` option when creating your
410
+ LRUCache instance. This option accepts any object with a `now`
411
+ method that returns a number.
412
+
413
+ For example, this would be a very bare-bones time-mocking system
414
+ you could use in your tests, without any particular test
415
+ framework:
416
+
417
+ ```ts
418
+ import { LRUCache } from 'lru-cache'
419
+
420
+ let myClockTime = 0
421
+
422
+ const cache = new LRUCache<string>({
423
+ max: 10,
424
+ ttl: 1000,
425
+ perf: {
426
+ now: () => myClockTime,
427
+ },
428
+ })
429
+
430
+ // run tests, updating myClockTime as needed
431
+ ```
432
+
433
+ ## Breaking Changes in Version 7
434
+
435
+ This library changed to a different algorithm and internal data
436
+ structure in version 7, yielding significantly better
437
+ performance, albeit with some subtle changes as a result.
438
+
439
+ If you were relying on the internals of LRUCache in version 6 or
440
+ before, it probably will not work in version 7 and above.
441
+
442
+ ## Breaking Changes in Version 8
443
+
444
+ - The `fetchContext` option was renamed to `context`, and may no
445
+ longer be set on the cache instance itself.
446
+ - Rewritten in TypeScript, so pretty much all the types moved
447
+ around a lot.
448
+ - The AbortController/AbortSignal polyfill was removed. For this
449
+ reason, **Node version 16.14.0 or higher is now required**.
450
+ - Internal properties were moved to actual private class
451
+ properties.
452
+ - Keys and values must not be `null` or `undefined`.
453
+ - Minified export available at `'lru-cache/min'`, for both CJS
454
+ and MJS builds.
455
+
456
+ ## Breaking Changes in Version 9
457
+
458
+ - Named export only, no default export.
459
+ - AbortController polyfill returned, albeit with a warning when
460
+ used.
461
+
462
+ ## Breaking Changes in Version 10
463
+
464
+ - `cache.fetch()` return type is now `Promise<V | undefined>`
465
+ instead of `Promise<V | void>`. This is an irrelevant change
466
+ practically speaking, but can require changes for TypeScript
467
+ users.
468
+
469
+ For more info, see the [change log](CHANGELOG.md).
@@ -0,0 +1,7 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.tracing = exports.metrics = void 0;
4
+ const dummy = { hasSubscribers: false };
5
+ exports.metrics = dummy;
6
+ exports.tracing = dummy;
7
+ //# sourceMappingURL=diagnostics-channel-browser.js.map