@voltro/cache 0.1.0

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 (8) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/LICENSE +57 -0
  3. package/README.md +26 -0
  4. package/SECURITY.md +56 -0
  5. package/THIRD-PARTY-NOTICES.md +491 -0
  6. package/dist/index.d.ts +191 -0
  7. package/dist/index.js +245 -0
  8. package/package.json +43 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,52 @@
1
+ # Changelog
2
+
3
+ All notable changes to the `@voltro/*` packages are recorded here. The format
4
+ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
5
+
6
+ ## Stability contract — read this before you pin a version
7
+
8
+ Voltro is **`0.x` — pre-1.0, and deliberately so.** Under SemVer, `0.y.z` means
9
+ "anything MAY change." We hold to exactly that, stated out loud:
10
+
11
+ - **Pin exact versions.** Depend on `@voltro/runtime@0.4.2`, never `^0.4.2` or
12
+ `~0.4.2`. There is no compatible-range promise below 1.0.
13
+ - **Every MINOR may break.** Breaking changes land on a minor bump (`0.4.x →
14
+ 0.5.0`); patches (`0.4.1 → 0.4.2`) are additive or fixes only. This is the
15
+ standard `0.x` reading of SemVer — the minor slot carries breaking under `0.x`.
16
+ - **Read this changelog before upgrading.** The `⚠ BREAKING` section of each
17
+ release lists every incompatible change with its migration. It is the only
18
+ migration path we provide — there is no deprecation cycle, no compat shim.
19
+ - **All packages release together (lockstep).** One coordinated version across
20
+ the whole framework; the git tag is the source of truth.
21
+
22
+ This is not a placeholder disclaimer — it is the contract. The framework is
23
+ refactored aggressively while it has no external stability obligations, and that
24
+ velocity is the point. A stable-core tier and per-package `1.0` graduation are
25
+ planned, but not yet; until then, treat the whole surface as movable and pin
26
+ exact.
27
+
28
+ The **public API** of each package is its `publishConfig.exports` entry points,
29
+ minus anything marked `@internal` (those are cross-package internals and are
30
+ stripped from the published `.d.ts`). Importing a deep path that isn't an
31
+ exported entry point is unsupported.
32
+
33
+ ---
34
+
35
+ ## [Unreleased]
36
+
37
+ _Changes staged for the next release accumulate here (rolled up from
38
+ `.changes/*.md` at tag time — see `.changes/README.md`)._
39
+
40
+ ---
41
+
42
+ ## [0.1.0]
43
+
44
+ Initial pre-release baseline. This is the starting point the changelog tracks
45
+ from; it is not an exhaustive history of prior development. The framework ships
46
+ as `@voltro/*` packages spanning the runtime, database/query layer, web client
47
+ and router, durable workflows, the CLI, and the plugin ecosystem
48
+ (auth, storage, mail, billing, observability, and more). Not published to a
49
+ public registry yet.
50
+
51
+ Subsequent releases record their deltas from here under dated headings, with
52
+ `⚠ BREAKING` first.
package/LICENSE ADDED
@@ -0,0 +1,57 @@
1
+ Voltro — Proprietary Software License
2
+
3
+ Copyright (c) 2026 Voltro UG. All rights reserved.
4
+
5
+ This software and all associated source code, documentation, and other
6
+ materials (the "Software") are the proprietary property of Voltro UG
7
+ ("Voltro"). This is NOT open-source software.
8
+
9
+ Your access to and use of the Software is governed exclusively by the Voltro
10
+ Terms of Service at:
11
+
12
+ https://voltro.cloud/legal/terms
13
+
14
+ By downloading, installing, or using the Software you agree to those Terms.
15
+ Subject to and conditioned on your continued compliance with them, Voltro
16
+ grants you a limited, non-exclusive, non-transferable, non-sublicensable,
17
+ revocable license to use the Software. All rights not expressly granted in the
18
+ Terms are reserved by Voltro. If you do not agree to the Terms, you have no
19
+ license and may not use the Software.
20
+
21
+ The Terms of Service — including the scope of permitted use, plan
22
+ entitlements, fees, and pricing — may change from time to time. The version in
23
+ force is the one published at the URL above. Commercial terms and pricing are
24
+ NOT part of this notice and are not fixed by, or granted in perpetuity by, the
25
+ version of the Software in which this file appears.
26
+
27
+ Permitted use — your own software. Voltro is a development framework. You may
28
+ use the Software to build, run, and commercially distribute your own
29
+ applications and services, and to charge your own customers for them, without
30
+ owing Voltro any share of that revenue or any further permission beyond the
31
+ Terms. Applications you build with the Software are yours.
32
+
33
+ Prohibited use — reselling Voltro. You may NOT redistribute, resell,
34
+ sublicense, publish, or otherwise provide the Software itself — in whole or in
35
+ part, in source or compiled form — to third parties as a library, framework,
36
+ SDK, template, starter, or development tool for them to build upon, whether
37
+ standalone or repackaged. Shipping the Software as a non-separable, bundled
38
+ dependency inside an application you deliver (for example, compiled into your
39
+ deployed app) is permitted; extracting or re-exposing it as a reusable
40
+ component for others is not.
41
+
42
+ Except as expressly permitted above or by the Terms, you may not copy, modify,
43
+ merge, publish, sublicense, sell, distribute, or create derivative works of the
44
+ Software, in whole or in part.
45
+
46
+ Third-party open-source components distributed alongside the Software are the
47
+ property of their respective owners and are licensed under their own terms; see
48
+ THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
49
+ rights, or extends Voltro's, in those components.
50
+
51
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
52
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
53
+ FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
54
+ VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
55
+ OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
56
+
57
+ For licensing inquiries, contact Voltro UG.
package/README.md ADDED
@@ -0,0 +1,26 @@
1
+ <div align="center">
2
+
3
+ # @voltro/cache
4
+
5
+ **Effect-native cache primitive — memory + RESP (Redis/Valkey/KeyDB/Dragonfly/Upstash) backends, tag invalidation, single-flight wrap.**
6
+
7
+ [📖 Documentation](https://docs.voltro.dev/docs/caching/overview) · [Changelog](./CHANGELOG.md) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
8
+
9
+ </div>
10
+
11
+ ---
12
+
13
+ ```sh
14
+ npm install @voltro/cache
15
+ ```
16
+
17
+ > ### [→ Read the documentation for @voltro/cache](https://docs.voltro.dev/docs/caching/overview)
18
+
19
+ Installation, guides, the full API reference, and examples all live in the
20
+ **[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
21
+ deliberately short so there is nothing here to drift out of date.
22
+
23
+ ## License
24
+
25
+ Proprietary. © 2026 Voltro UG. Your use is governed by the
26
+ [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
package/SECURITY.md ADDED
@@ -0,0 +1,56 @@
1
+ # Security Policy
2
+
3
+ We take the security of Voltro and the applications built on it seriously. This
4
+ document explains how to report a vulnerability and what to expect in return.
5
+
6
+ ## Reporting a vulnerability
7
+
8
+ **Please do not open public issues or discuss suspected vulnerabilities in
9
+ public channels.** Report them privately by email:
10
+
11
+ **security contact: [support@voltro.dev](mailto:support@voltro.dev)**
12
+ (subject line: `SECURITY`).
13
+
14
+ Include, where you can:
15
+
16
+ - the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
17
+ - a description of the issue and its impact;
18
+ - a minimal reproduction or proof of concept;
19
+ - any suggested remediation.
20
+
21
+ If you'd like to encrypt your report, ask in a first plain email and we'll
22
+ arrange a key.
23
+
24
+ ## What to expect
25
+
26
+ - **Acknowledgement** of your report within **3 business days**.
27
+ - An initial assessment (severity, affected surface) and a remediation plan as
28
+ soon as we've reproduced the issue.
29
+ - **Coordinated disclosure:** we'll agree a disclosure timeline with you and
30
+ credit you in the release notes if you wish. Please give us reasonable time to
31
+ ship a fix before any public disclosure.
32
+
33
+ We do not currently run a paid bug-bounty program, but we genuinely appreciate
34
+ responsible disclosure and will credit reporters.
35
+
36
+ ## Software Bill of Materials (SBOM)
37
+
38
+ A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
39
+ published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
40
+ security team needs it, request it at
41
+ [support@voltro.dev](mailto:support@voltro.dev).
42
+
43
+ ## Supported versions
44
+
45
+ Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
46
+ each `@voltro/*` package receives security fixes.** Please upgrade to the latest
47
+ release before reporting, and pin exact versions in production.
48
+
49
+ ## Scope
50
+
51
+ In scope: the published `@voltro/*` packages and the framework's own code.
52
+
53
+ Out of scope: vulnerabilities in third-party dependencies that are already
54
+ tracked upstream (we monitor these via a production-dependency audit gate in
55
+ CI), and issues that require a non-default, explicitly-unsafe configuration. If
56
+ you're unsure, report it anyway — we'd rather hear about it.
package/THIRD-PARTY-NOTICES.md ADDED
@@ -0,0 +1,491 @@
1
+ # Third-Party Notices — @voltro/cache
2
+
3
+ This package depends on the open-source software listed below. Each is the
4
+ property of its respective copyright holders and is used under the terms of
5
+ its license. This file is provided for attribution; it grants no rights in
6
+ @voltro/cache itself, which is proprietary (see LICENSE).
7
+
8
+ Generated from the resolved runtime dependency closure (11 packages).
9
+
10
+ ---
11
+
12
+ ## @ioredis/commands@1.10.0
13
+
14
+ License: MIT
15
+
16
+ ```
17
+ The MIT License (MIT)
18
+
19
+ Copyright (c) 2022 Zihua Li
20
+ Copyright (c) 2015 NodeRedis
21
+
22
+ Permission is hereby granted, free of charge, to any person obtaining a copy
23
+ of this software and associated documentation files (the "Software"), to deal
24
+ in the Software without restriction, including without limitation the rights
25
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
26
+ copies of the Software, and to permit persons to whom the Software is
27
+ furnished to do so, subject to the following conditions:
28
+
29
+ The above copyright notice and this permission notice shall be included in all
30
+ copies or substantial portions of the Software.
31
+
32
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
33
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
34
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
35
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
36
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
37
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
38
+ SOFTWARE.
39
+ ```
40
+
41
+ ## @upstash/redis@1.38.0
42
+
43
+ License: MIT
44
+
45
+ ```
46
+ The MIT License (MIT)
47
+
48
+ Copyright (c) 2021 Upstash, Inc.
49
+
50
+ Permission is hereby granted, free of charge, to any person obtaining a copy
51
+ of this software and associated documentation files (the "Software"), to deal
52
+ in the Software without restriction, including without limitation the rights
53
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
54
+ copies of the Software, and to permit persons to whom the Software is
55
+ furnished to do so, subject to the following conditions:
56
+
57
+ The above copyright notice and this permission notice shall be included in all
58
+ copies or substantial portions of the Software.
59
+
60
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
61
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
62
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
63
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
64
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
65
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
66
+ SOFTWARE.
67
+ ```
68
+
69
+ ## cluster-key-slot@1.1.1
70
+
71
+ License: Apache-2.0
72
+
73
+ ```
74
+ Copyright (c) 2018 Mike Diarmid (Salakar) <mike.diarmid@gmail.com>
75
+
76
+ Licensed under the Apache License, Version 2.0 (the "License");
77
+ you may not use this library except in compliance with the License.
78
+ You may obtain a copy of the License at
79
+
80
+ http://www.apache.org/licenses/LICENSE-2.0
81
+
82
+ Unless required by applicable law or agreed to in writing, software
83
+ distributed under the License is distributed on an "AS IS" BASIS,
84
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
85
+ See the License for the specific language governing permissions and
86
+ limitations under the License.
87
+ ```
88
+
89
+ ## debug@4.4.3
90
+
91
+ License: MIT
92
+
93
+ ```
94
+ (The MIT License)
95
+
96
+ Copyright (c) 2014-2017 TJ Holowaychuk <tj@vision-media.ca>
97
+ Copyright (c) 2018-2021 Josh Junon
98
+
99
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software
100
+ and associated documentation files (the 'Software'), to deal in the Software without restriction,
101
+ including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
102
+ and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
103
+ subject to the following conditions:
104
+
105
+ The above copyright notice and this permission notice shall be included in all copies or substantial
106
+ portions of the Software.
107
+
108
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
109
+ LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
110
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
111
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
112
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
113
+ ```
114
+
115
+ ## denque@2.1.0
116
+
117
+ License: Apache-2.0
118
+
119
+ ```
120
+ Apache License
121
+ Version 2.0, January 2004
122
+ http://www.apache.org/licenses/
123
+
124
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
125
+
126
+ 1. Definitions.
127
+
128
+ "License" shall mean the terms and conditions for use, reproduction,
129
+ and distribution as defined by Sections 1 through 9 of this document.
130
+
131
+ "Licensor" shall mean the copyright owner or entity authorized by
132
+ the copyright owner that is granting the License.
133
+
134
+ "Legal Entity" shall mean the union of the acting entity and all
135
+ other entities that control, are controlled by, or are under common
136
+ control with that entity. For the purposes of this definition,
137
+ "control" means (i) the power, direct or indirect, to cause the
138
+ direction or management of such entity, whether by contract or
139
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
140
+ outstanding shares, or (iii) beneficial ownership of such entity.
141
+
142
+ "You" (or "Your") shall mean an individual or Legal Entity
143
+ exercising permissions granted by this License.
144
+
145
+ "Source" form shall mean the preferred form for making modifications,
146
+ including but not limited to software source code, documentation
147
+ source, and configuration files.
148
+
149
+ "Object" form shall mean any form resulting from mechanical
150
+ transformation or translation of a Source form, including but
151
+ not limited to compiled object code, generated documentation,
152
+ and conversions to other media types.
153
+
154
+ "Work" shall mean the work of authorship, whether in Source or
155
+ Object form, made available under the License, as indicated by a
156
+ copyright notice that is included in or attached to the work
157
+ (an example is provided in the Appendix below).
158
+
159
+ "Derivative Works" shall mean any work, whether in Source or Object
160
+ form, that is based on (or derived from) the Work and for which the
161
+ editorial revisions, annotations, elaborations, or other modifications
162
+ represent, as a whole, an original work of authorship. For the purposes
163
+ of this License, Derivative Works shall not include works that remain
164
+ separable from, or merely link (or bind by name) to the interfaces of,
165
+ the Work and Derivative Works thereof.
166
+
167
+ "Contribution" shall mean any work of authorship, including
168
+ the original version of the Work and any modifications or additions
169
+ to that Work or Derivative Works thereof, that is intentionally
170
+ submitted to Licensor for inclusion in the Work by the copyright owner
171
+ or by an individual or Legal Entity authorized to submit on behalf of
172
+ the copyright owner. For the purposes of this definition, "submitted"
173
+ means any form of electronic, verbal, or written communication sent
174
+ to the Licensor or its representatives, including but not limited to
175
+ communication on electronic mailing lists, source code control systems,
176
+ and issue tracking systems that are managed by, or on behalf of, the
177
+ Licensor for the purpose of discussing and improving the Work, but
178
+ excluding communication that is conspicuously marked or otherwise
179
+ designated in writing by the copyright owner as "Not a Contribution."
180
+
181
+ "Contributor" shall mean Licensor and any individual or Legal Entity
182
+ on behalf of whom a Contribution has been received by Licensor and
183
+ subsequently incorporated within the Work.
184
+
185
+ 2. Grant of Copyright License. Subject to the terms and conditions of
186
+ this License, each Contributor hereby grants to You a perpetual,
187
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
188
+ copyright license to reproduce, prepare Derivative Works of,
189
+ publicly display, publicly perform, sublicense, and distribute the
190
+ Work and such Derivative Works in Source or Object form.
191
+
192
+ 3. Grant of Patent License. Subject to the terms and conditions of
193
+ this License, each Contributor hereby grants to You a perpetual,
194
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
195
+ (except as stated in this section) patent license to make, have made,
196
+ use, offer to sell, sell, import, and otherwise transfer the Work,
197
+ where such license applies only to those patent claims licensable
198
+ by such Contributor that are necessarily infringed by their
199
+ Contribution(s) alone or by combination of their Contribution(s)
200
+ with the Work to which such Contribution(s) was submitted. If You
201
+ institute patent litigation against any entity (including a
202
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
203
+ or a Contribution incorporated within the Work constitutes direct
204
+ or contributory patent infringement, then any patent licenses
205
+ granted to You under this License for that Work shall terminate
206
+ as of the date such litigation is filed.
207
+
208
+ 4. Redistribution. You may reproduce and distribute copies of the
209
+ Work or Derivative Works thereof in any medium, with or without
210
+ modifications, and in Source or Object form, provided that You
211
+ meet the following conditions:
212
+
213
+ (a) You must give any other recipients of the Work or
214
+ Derivative Works a copy of this License; and
215
+
216
+ (b) You must cause any modified files to carry prominent notices
217
+ stating that You changed the files; and
218
+
219
+ (c) You must retain, in the Source form of any Derivative Works
220
+ that You distribute, all copyright, patent, trademark, and
221
+ attribution notices from the Source form of the Work,
222
+ excluding those notices that do not pertain to any part of
223
+ the Derivative Works; and
224
+
225
+ (d) If the Work includes a "NOTICE" text file as part of its
226
+ distribution, then any Derivative Works that You distribute must
227
+ include a readable copy of the attribution notices contained
228
+ within such NOTICE file, excluding those notices that do not
229
+ pertain to any part of the Derivative Works, in at least one
230
+ of the following places: within a NOTICE text file distributed
231
+ as part of the Derivative Works; within the Source form or
232
+ documentation, if provided along with the Derivative Works; or,
233
+ within a display generated by the Derivative Works, if and
234
+ wherever such third-party notices normally appear. The contents
235
+ of the NOTICE file are for informational purposes only and
236
+ do not modify the License. You may add Your own attribution
237
+ notices within Derivative Works that You distribute, alongside
238
+ or as an addendum to the NOTICE text from the Work, provided
239
+ that such additional attribution notices cannot be construed
240
+ as modifying the License.
241
+
242
+ You may add Your own copyright statement to Your modifications and
243
+ may provide additional or different license terms and conditions
244
+ for use, reproduction, or distribution of Your modifications, or
245
+ for any such Derivative Works as a whole, provided Your use,
246
+ reproduction, and distribution of the Work otherwise complies with
247
+ the conditions stated in this License.
248
+
249
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
250
+ any Contribution intentionally submitted for inclusion in the Work
251
+ by You to the Licensor shall be under the terms and conditions of
252
+ this License, without any additional terms or conditions.
253
+ Notwithstanding the above, nothing herein shall supersede or modify
254
+ the terms of any separate license agreement you may have executed
255
+ with Licensor regarding such Contributions.
256
+
257
+ 6. Trademarks. This License does not grant permission to use the trade
258
+ names, trademarks, service marks, or product names of the Licensor,
259
+ except as required for reasonable and customary use in describing the
260
+ origin of the Work and reproducing the content of the NOTICE file.
261
+
262
+ 7. Disclaimer of Warranty. Unless required by applicable law or
263
+ agreed to in writing, Licensor provides the Work (and each
264
+ Contributor provides its Contributions) on an "AS IS" BASIS,
265
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
266
+ implied, including, without limitation, any warranties or conditions
267
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
268
+ PARTICULAR PURPOSE. You are solely responsible for determining the
269
+ appropriateness of using or redistributing the Work and assume any
270
+ risks associated with Your exercise of permissions under this License.
271
+
272
+ 8. Limitation of Liability. In no event and under no legal theory,
273
+ whether in tort (including negligence), contract, or otherwise,
274
+ unless required by applicable law (such as deliberate and grossly
275
+ negligent acts) or agreed to in writing, shall any Contributor be
276
+ liable to You for damages, including any direct, indirect, special,
277
+ incidental, or consequential damages of any character arising as a
278
+ result of this License or out of the use or inability to use the
279
+ Work (including but not limited to damages for loss of goodwill,
280
+ work stoppage, computer failure or malfunction, or any and all
281
+ other commercial damages or losses), even if such Contributor
282
+ has been advised of the possibility of such damages.
283
+
284
+ 9. Accepting Warranty or Additional Liability. While redistributing
285
+ the Work or Derivative Works thereof, You may choose to offer,
286
+ and charge a fee for, acceptance of support, warranty, indemnity,
287
+ or other liability obligations and/or rights consistent with this
288
+ License. However, in accepting such obligations, You may act only
289
+ on Your own behalf and on Your sole responsibility, not on behalf
290
+ of any other Contributor, and only if You agree to indemnify,
291
+ defend, and hold each Contributor harmless for any liability
292
+ incurred by, or claims asserted against, such Contributor by reason
293
+ of your accepting any such warranty or additional liability.
294
+
295
+ END OF TERMS AND CONDITIONS
296
+
297
+ APPENDIX: How to apply the Apache License to your work.
298
+
299
+ To apply the Apache License to your work, attach the following
300
+ boilerplate notice, with the fields enclosed by brackets "[]"
301
+ replaced with your own identifying information. (Don't include
302
+ the brackets!) The text should be enclosed in the appropriate
303
+ comment syntax for the file format. We also recommend that a
304
+ file or class name and description of purpose be included on the
305
+ same "printed page" as the copyright notice for easier
306
+ identification within third-party archives.
307
+
308
+ Copyright 2018-present Invertase Limited
309
+
310
+ Licensed under the Apache License, Version 2.0 (the "License");
311
+ you may not use this file except in compliance with the License.
312
+ You may obtain a copy of the License at
313
+
314
+ http://www.apache.org/licenses/LICENSE-2.0
315
+
316
+ Unless required by applicable law or agreed to in writing, software
317
+ distributed under the License is distributed on an "AS IS" BASIS,
318
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
319
+ See the License for the specific language governing permissions and
320
+ limitations under the License.
321
+ ```
322
+
323
+ ## ioredis@5.11.1
324
+
325
+ License: MIT
326
+
327
+ ```
328
+ The MIT License (MIT)
329
+
330
+ Copyright (c) 2015-2022 Zihua Li
331
+
332
+ Permission is hereby granted, free of charge, to any person obtaining a copy
333
+ of this software and associated documentation files (the "Software"), to deal
334
+ in the Software without restriction, including without limitation the rights
335
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
336
+ copies of the Software, and to permit persons to whom the Software is
337
+ furnished to do so, subject to the following conditions:
338
+
339
+ The above copyright notice and this permission notice shall be included in all
340
+ copies or substantial portions of the Software.
341
+
342
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
343
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
344
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
345
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
346
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
347
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
348
+ SOFTWARE.
349
+ ```
350
+
351
+ ## ms@2.1.3
352
+
353
+ License: MIT
354
+
355
+ ```
356
+ The MIT License (MIT)
357
+
358
+ Copyright (c) 2020 Vercel, Inc.
359
+
360
+ Permission is hereby granted, free of charge, to any person obtaining a copy
361
+ of this software and associated documentation files (the "Software"), to deal
362
+ in the Software without restriction, including without limitation the rights
363
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
364
+ copies of the Software, and to permit persons to whom the Software is
365
+ furnished to do so, subject to the following conditions:
366
+
367
+ The above copyright notice and this permission notice shall be included in all
368
+ copies or substantial portions of the Software.
369
+
370
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
371
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
372
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
373
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
374
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
375
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
376
+ SOFTWARE.
377
+ ```
378
+
379
+ ## redis-errors@1.2.0
380
+
381
+ License: MIT
382
+
383
+ ```
384
+ The MIT License (MIT)
385
+
386
+ Copyright (c) 2017 Ruben Bridgewater
387
+
388
+ Permission is hereby granted, free of charge, to any person obtaining a copy
389
+ of this software and associated documentation files (the "Software"), to deal
390
+ in the Software without restriction, including without limitation the rights
391
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
392
+ copies of the Software, and to permit persons to whom the Software is
393
+ furnished to do so, subject to the following conditions:
394
+
395
+ The above copyright notice and this permission notice shall be included in all
396
+ copies or substantial portions of the Software.
397
+
398
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
399
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
400
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
401
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
402
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
403
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
404
+ SOFTWARE.
405
+ ```
406
+
407
+ ## redis-parser@3.0.0
408
+
409
+ License: MIT
410
+
411
+ ```
412
+ The MIT License (MIT)
413
+
414
+ Copyright (c) 2015 NodeRedis
415
+
416
+ Permission is hereby granted, free of charge, to any person obtaining a copy
417
+ of this software and associated documentation files (the "Software"), to deal
418
+ in the Software without restriction, including without limitation the rights
419
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
420
+ copies of the Software, and to permit persons to whom the Software is
421
+ furnished to do so, subject to the following conditions:
422
+
423
+ The above copyright notice and this permission notice shall be included in all
424
+ copies or substantial portions of the Software.
425
+
426
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
427
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
428
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
429
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
430
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
431
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
432
+ SOFTWARE.
433
+ ```
434
+
435
+ ## standard-as-callback@2.1.0
436
+
437
+ License: MIT
438
+
439
+ ```
440
+ MIT License
441
+
442
+ Copyright (c) 2018 Zihua Li
443
+ Copyright (c) 2013-2017 Petka Antonov
444
+
445
+ Permission is hereby granted, free of charge, to any person obtaining a copy
446
+ of this software and associated documentation files (the "Software"), to deal
447
+ in the Software without restriction, including without limitation the rights
448
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
449
+ copies of the Software, and to permit persons to whom the Software is
450
+ furnished to do so, subject to the following conditions:
451
+
452
+ The above copyright notice and this permission notice shall be included in all
453
+ copies or substantial portions of the Software.
454
+
455
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
456
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
457
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
458
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
459
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
460
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
461
+ SOFTWARE.
462
+ ```
463
+
464
+ ## uncrypto@0.1.3
465
+
466
+ License: MIT
467
+
468
+ ```
469
+ MIT License
470
+
471
+ Copyright (c) Pooya Parsa <pooya@pi0.io>
472
+
473
+ Permission is hereby granted, free of charge, to any person obtaining a copy
474
+ of this software and associated documentation files (the "Software"), to deal
475
+ in the Software without restriction, including without limitation the rights
476
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
477
+ copies of the Software, and to permit persons to whom the Software is
478
+ furnished to do so, subject to the following conditions:
479
+
480
+ The above copyright notice and this permission notice shall be included in all
481
+ copies or substantial portions of the Software.
482
+
483
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
484
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
485
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
486
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
487
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
488
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
489
+ SOFTWARE.
490
+ ```
491
+
package/dist/index.d.ts ADDED
@@ -0,0 +1,191 @@
1
+ import { ConfigError } from 'effect';
2
+ import { Context } from 'effect';
3
+ import { Effect } from 'effect';
4
+ import { Layer } from 'effect';
5
+ import { Option } from 'effect';
6
+ import { Schema } from 'effect';
7
+ import { Scope } from 'effect';
8
+ import { Stream } from 'effect';
9
+
10
+ export declare class Cache extends Cache_base {
11
+ }
12
+
13
+ declare const Cache_base: Effect.Service.Class<Cache, "@voltro/Cache", {
14
+ readonly effect: Effect.Effect<{
15
+ /** Read a typed value. `None` on miss/expiry. */
16
+ readonly get: <A = unknown>(key: string) => Effect.Effect<Option.Option<A>, CacheError>;
17
+ readonly set: <A>(key: string, value: A, options?: CacheSetOptions) => Effect.Effect<void, CacheError>;
18
+ readonly setWithTags: <A>(key: string, value: A, options: CacheSetWithTagsOptions) => Effect.Effect<void, CacheError>;
19
+ /** Write-through with the SAME storage shape `wrap` uses (incl. the
20
+ * SWR envelope) — so a value written here is read back identically
21
+ * by a later `wrap`. The dispatcher uses this to keep cached
22
+ * snapshots warm from its live recompute. */
23
+ readonly put: <A>(key: string, options: WrapOptions, value: A) => Effect.Effect<void, CacheError>;
24
+ readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
25
+ readonly has: (key: string) => Effect.Effect<boolean, CacheError>;
26
+ readonly clear: () => Effect.Effect<void, CacheError>;
27
+ readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
28
+ readonly wrap: <A, E, R>(key: string, options: WrapOptions, compute: Effect.Effect<A, E, R>) => Effect.Effect<A, E | CacheError, R>;
29
+ /** A named, key-prefixed partition with its own default ttl/swr/tags.
30
+ * Keys become `<name>:<key>`; per-call options override the defaults;
31
+ * tags stay global (unprefixed) so bus invalidation still reaches
32
+ * partitioned entries. */
33
+ readonly partition: (name: string, defaults?: PartitionDefaults) => CachePartition;
34
+ /** Read the hit/miss counters + derived hit-rate (0–1). Drives the
35
+ * dashboard cache panel. */
36
+ readonly stats: () => Effect.Effect<{
37
+ hits: number;
38
+ misses: number;
39
+ hitRate: number;
40
+ }>;
41
+ }, never, CacheStore>;
42
+ }>;
43
+
44
+ export declare class CacheError extends CacheError_base {
45
+ }
46
+
47
+ declare const CacheError_base: Schema.TaggedErrorClass<CacheError, "CacheError", {
48
+ readonly _tag: Schema.tag<"CacheError">;
49
+ } & {
50
+ /** Which op failed: 'get' | 'set' | 'setWithTags' | 'remove' | 'has' |
51
+ * 'clear' | 'invalidateTag' | 'connect' | 'serialize' | 'deserialize'. */
52
+ operation: typeof Schema.String;
53
+ /** The cache key (or tag) involved; '' for clear / connect. */
54
+ key: typeof Schema.String;
55
+ /** `String(originalError)` — round-trip-safe diagnostic form. */
56
+ cause: typeof Schema.String;
57
+ }>;
58
+
59
+ export declare namespace CacheLayer {
60
+ export {
61
+ layer
62
+ }
63
+ }
64
+
65
+ /**
66
+ * A named, key-prefixed VIEW over the cache — one logical namespace per
67
+ * concern (`sessions`, `reports`, …) with its own default TTL/SWR. Keys are
68
+ * prefixed `<name>:`, so partitions can't collide, and per-call options
69
+ * override the partition defaults.
70
+ *
71
+ * Tags are NOT prefixed — they stay global on purpose, so a table-change
72
+ * invalidation through the bus still drops matching entries in every
73
+ * partition. A partition shares the parent cache's BACKEND; to put a concern
74
+ * on a different backend/server, configure it as its own concern (e.g. the
75
+ * durable `Kv` service, or a separately-provided cache) — the connection
76
+ * registry lets each point at the same or a different Redis.
77
+ */
78
+ export declare interface CachePartition {
79
+ get<A = unknown>(key: string): Effect.Effect<Option.Option<A>, CacheError>;
80
+ set<A>(key: string, value: A, options?: CacheSetOptions): Effect.Effect<void, CacheError>;
81
+ has(key: string): Effect.Effect<boolean, CacheError>;
82
+ remove(key: string): Effect.Effect<boolean, CacheError>;
83
+ /** Cache-aside within this partition. Partition defaults fill any option the
84
+ * call omits; tags stay global (unprefixed). */
85
+ wrap<A, E, R>(key: string, options: WrapOptions, compute: Effect.Effect<A, E, R>): Effect.Effect<A, E | CacheError, R>;
86
+ /** Invalidate a (global, unprefixed) tag — shared across partitions. */
87
+ invalidateTag(tag: string): Effect.Effect<number, CacheError>;
88
+ }
89
+
90
+ export declare interface CacheSetOptions {
91
+ /** Time-to-live in milliseconds. Omit for no expiry (entry lives until
92
+ * evicted, capacity-pressured, or invalidated by tag). */
93
+ readonly ttlMs?: number;
94
+ }
95
+
96
+ export declare interface CacheSetWithTagsOptions extends CacheSetOptions {
97
+ /** Tags this entry belongs to. `invalidateTag(tag)` drops every entry
98
+ * carrying that tag. */
99
+ readonly tags?: ReadonlyArray<string>;
100
+ }
101
+
102
+ export declare class CacheStore extends CacheStore_base {
103
+ }
104
+
105
+ declare const CacheStore_base: Context.TagClass<CacheStore, "@voltro/CacheStore", CacheStoreShape>;
106
+
107
+ export declare interface CacheStoreShape {
108
+ /** Read a value. `None` on miss OR expiry (expired entries are lazily
109
+ * evicted on read). */
110
+ readonly get: (key: string) => Effect.Effect<Option.Option<unknown>, CacheError>;
111
+ /** Write a value with an optional ms TTL. Overwrites any existing entry
112
+ * (clearing its old tag memberships). */
113
+ readonly set: (key: string, value: unknown, options?: CacheSetOptions) => Effect.Effect<void, CacheError>;
114
+ /** Write a value AND register it under the given tags. */
115
+ readonly setWithTags: (key: string, value: unknown, options: CacheSetWithTagsOptions) => Effect.Effect<void, CacheError>;
116
+ /** Delete one key (and its tag memberships). Resolves `true` if it existed. */
117
+ readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
118
+ /** Existence check honouring expiry, without deserializing the value. */
119
+ readonly has: (key: string) => Effect.Effect<boolean, CacheError>;
120
+ /** Drop every entry in this cache's namespace. Scoped to the backend's
121
+ * key-prefix — never a global flush on a shared server. */
122
+ readonly clear: () => Effect.Effect<void, CacheError>;
123
+ /** Delete every key registered under `tag`, then drop the tag index.
124
+ * Resolves the count of keys removed. */
125
+ readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
126
+ }
127
+
128
+ export declare class InvalidationBus extends InvalidationBus_base {
129
+ }
130
+
131
+ declare const InvalidationBus_base: Effect.Service.Class<InvalidationBus, "@voltro/InvalidationBus", {
132
+ readonly scoped: Effect.Effect<{
133
+ readonly publish: (table: string) => Effect.Effect<void>;
134
+ readonly changes: Stream.Stream<string, never, never>;
135
+ readonly addSink: (handle: (table: string) => Effect.Effect<unknown, unknown>) => Effect.Effect<void>;
136
+ }, never, Scope.Scope>;
137
+ }>;
138
+
139
+ /**
140
+ * `Layer<Cache>` whose backend is chosen from the environment. Provide
141
+ * this in the app's layer stack so handlers can `yield* Cache`.
142
+ */
143
+ declare const layer: Layer.Layer<Cache, ConfigError.ConfigError | CacheError>;
144
+
145
+ /** `Layer<CacheStore>` backed by an in-process `Ref`. */
146
+ export declare const layerMemory: (options?: MemoryCacheOptions) => Layer.Layer<CacheStore>;
147
+
148
+ /** `Layer<CacheStore>` backed by a RESP server (Redis/Valkey/KeyDB/Dragonfly/Upstash). */
149
+ export declare const layerRedis: (options: RedisCacheOptions) => Layer.Layer<CacheStore, CacheError>;
150
+
151
+ export declare interface MemoryCacheOptions {
152
+ /** Hard cap on live entry count. When exceeded, oldest-by-insertion
153
+ * entries are evicted — the backstop for entries that expired but were
154
+ * never read (lazy eviction never fired). Omit for unbounded. */
155
+ readonly maxEntries?: number;
156
+ /** Injectable clock — a plain `() => epoch-ms` used for TTL expiry instead
157
+ * of Effect's ambient `Clock.currentTimeMillis`. Lets a caller drive
158
+ * expiry off a controlled clock (e.g. a test harness whose own frozen
159
+ * clock isn't Effect's `TestClock`) without standing up an Effect runtime
160
+ * + custom `Clock` layer. Omit to use the ambient Effect clock (the
161
+ * default — `TestClock` still drives it under Effect tests). */
162
+ readonly now?: () => number;
163
+ }
164
+
165
+ /** Per-partition default `WrapOptions`, applied when a call omits them. */
166
+ export declare interface PartitionDefaults {
167
+ readonly ttlMs?: number;
168
+ readonly swrMs?: number;
169
+ readonly tags?: ReadonlyArray<string>;
170
+ }
171
+
172
+ export declare interface RedisCacheOptions {
173
+ readonly driver: 'resp' | 'http';
174
+ /** Connection URL (`redis://…` / `rediss://…` for RESP, the REST URL for http). */
175
+ readonly url: string;
176
+ /** Auth token — http (Upstash REST) driver only. */
177
+ readonly token?: string;
178
+ readonly keyPrefix?: string;
179
+ }
180
+
181
+ export declare interface WrapOptions {
182
+ /** Fresh window in ms. After this the entry is stale (or gone, if no swr). */
183
+ readonly ttlMs?: number;
184
+ /** Stale-while-revalidate window in ms past `ttlMs`. While stale, the
185
+ * cached value is served immediately AND a background refresh runs. */
186
+ readonly swrMs?: number;
187
+ /** Tags for `invalidateTag` — typically the tables the compute reads. */
188
+ readonly tags?: ReadonlyArray<string>;
189
+ }
190
+
191
+ export { }
package/dist/index.js ADDED
@@ -0,0 +1,245 @@
1
+ import { Clock as e, Config as t, Context as n, Deferred as r, Effect as i, HashMap as a, HashSet as o, Layer as s, Metric as c, Option as l, PubSub as u, Ref as d, Schema as f, Scope as p, Stream as m, SynchronizedRef as h } from "effect";
2
+ import { commandRetry as g, connect as _ } from "@voltro/kv/connection";
3
+ //#region \0rolldown/runtime.js
4
+ var v = Object.defineProperty, y = (e, t) => {
5
+ let n = {};
6
+ for (var r in e) v(n, r, {
7
+ get: e[r],
8
+ enumerable: !0
9
+ });
10
+ return t || v(n, Symbol.toStringTag, { value: "Module" }), n;
11
+ }, b = class extends f.TaggedError()("CacheError", {
12
+ operation: f.String,
13
+ key: f.String,
14
+ cause: f.String
15
+ }) {}, x = class extends n.Tag("@voltro/CacheStore")() {}, S = {
16
+ entries: a.empty(),
17
+ tagIndex: a.empty(),
18
+ seq: 0
19
+ }, C = (e, t, n) => {
20
+ let r = e;
21
+ for (let e of n) {
22
+ let n = a.get(r, e);
23
+ if (l.isNone(n)) continue;
24
+ let i = o.remove(n.value, t);
25
+ r = o.size(i) === 0 ? a.remove(r, e) : a.set(r, e, i);
26
+ }
27
+ return r;
28
+ }, w = (e, t) => {
29
+ let n = a.get(e.entries, t);
30
+ return l.isNone(n) ? e : {
31
+ entries: a.remove(e.entries, t),
32
+ tagIndex: C(e.tagIndex, t, n.value.tags),
33
+ seq: e.seq
34
+ };
35
+ }, T = (e, t, n) => {
36
+ let r = a.get(e, t), i = l.isSome(r) ? o.add(r.value, n) : o.make(n);
37
+ return a.set(e, t, i);
38
+ }, E = (e, t) => {
39
+ let n = a.size(e.entries) - t;
40
+ if (n <= 0) return e;
41
+ let r = [];
42
+ for (let [t, n] of e.entries) r.push([t, n.seq]);
43
+ r.sort((e, t) => e[1] - t[1]);
44
+ let i = e;
45
+ for (let e = 0; e < n; e++) {
46
+ let t = r[e];
47
+ if (t === void 0) break;
48
+ i = w(i, t[0]);
49
+ }
50
+ return i;
51
+ }, D = (e, t, n, r, i, o) => {
52
+ let s = w(e, t), c = s.seq + 1, l = s.tagIndex;
53
+ for (let e of i) l = T(l, e, t);
54
+ let u = {
55
+ entries: a.set(s.entries, t, {
56
+ value: n,
57
+ expiresAt: r,
58
+ tags: i,
59
+ seq: c
60
+ }),
61
+ tagIndex: l,
62
+ seq: c
63
+ };
64
+ return o === void 0 ? u : E(u, o);
65
+ }, O = (e, t) => t === void 0 ? Infinity : e + t, k = (t) => i.gen(function* () {
66
+ let n = yield* d.make(S), r = t.maxEntries, o = t.now === void 0 ? e.currentTimeMillis : i.sync(t.now);
67
+ return {
68
+ get: (e) => o.pipe(i.flatMap((t) => d.modify(n, (n) => {
69
+ let r = a.get(n.entries, e);
70
+ return l.isNone(r) ? [l.none(), n] : r.value.expiresAt <= t ? [l.none(), w(n, e)] : [l.some(r.value.value), n];
71
+ }))),
72
+ set: (e, t, a) => o.pipe(i.flatMap((i) => d.update(n, (n) => D(n, e, t, O(i, a?.ttlMs), [], r)))),
73
+ setWithTags: (e, t, a) => o.pipe(i.flatMap((i) => d.update(n, (n) => D(n, e, t, O(i, a.ttlMs), a.tags ?? [], r)))),
74
+ remove: (e) => o.pipe(i.flatMap((t) => d.modify(n, (n) => {
75
+ let r = a.get(n.entries, e);
76
+ return l.isNone(r) ? [!1, n] : [r.value.expiresAt > t, w(n, e)];
77
+ }))),
78
+ has: (e) => o.pipe(i.flatMap((t) => d.modify(n, (n) => {
79
+ let r = a.get(n.entries, e);
80
+ return l.isNone(r) ? [!1, n] : r.value.expiresAt <= t ? [!1, w(n, e)] : [!0, n];
81
+ }))),
82
+ clear: () => d.set(n, S),
83
+ invalidateTag: (e) => d.modify(n, (t) => {
84
+ let n = a.get(t.tagIndex, e);
85
+ if (l.isNone(n)) return [0, t];
86
+ let r = t, i = 0;
87
+ for (let e of n.value) r = w(r, e), i += 1;
88
+ return [i, {
89
+ ...r,
90
+ tagIndex: a.remove(r.tagIndex, e)
91
+ }];
92
+ })
93
+ };
94
+ }), A = (e = {}) => s.effect(x, k(e)), j = (e) => _({
95
+ url: e.url,
96
+ driver: e.driver,
97
+ ...e.token === void 0 ? {} : { token: e.token }
98
+ }).pipe(i.mapError((e) => new b({
99
+ operation: "connect",
100
+ key: "",
101
+ cause: String(e)
102
+ }))), M = "\nlocal NOEXP = 9000000000000000\nlocal ttl = tonumber(ARGV[1])\nlocal now = tonumber(ARGV[2])\nlocal score\nif ttl < 0 then score = NOEXP else score = now + ttl end\nredis.call('ZADD', KEYS[1], score, ARGV[3])\nlocal top = redis.call('ZREVRANGE', KEYS[1], 0, 0, 'WITHSCORES')\nlocal maxScore = tonumber(top[2])\nif maxScore >= NOEXP then\n redis.call('PERSIST', KEYS[1])\nelse\n local rem = maxScore - now\n if rem < 1 then rem = 1 end\n redis.call('PEXPIRE', KEYS[1], rem)\nend\nreturn 1\n", N = (t) => i.gen(function* () {
103
+ let n = yield* i.acquireRelease(j(t), (e) => i.promise(() => e.close().catch(() => void 0))), r = t.keyPrefix ?? "voltro:cache", a = (e) => `${r}:v:${e}`, o = (e) => `${r}:t:${e}`, s = (e, t, r) => i.tryPromise({
104
+ try: () => r(n),
105
+ catch: (n) => new b({
106
+ operation: e,
107
+ key: t,
108
+ cause: String(n)
109
+ })
110
+ }).pipe(i.retry(g)), c = (e, t) => i.try({
111
+ try: () => JSON.stringify(t),
112
+ catch: (t) => new b({
113
+ operation: "serialize",
114
+ key: e,
115
+ cause: String(t)
116
+ })
117
+ }), u = (e, t) => i.try({
118
+ try: () => l.some(JSON.parse(t)),
119
+ catch: (t) => new b({
120
+ operation: "deserialize",
121
+ key: e,
122
+ cause: String(t)
123
+ })
124
+ }), d = (e) => s("clear", "", (t) => t.scan(e, `${r}:*`, 200)).pipe(i.flatMap(({ cursor: e, keys: t }) => (t.length > 0 ? s("clear", "", (e) => e.del(t)) : i.succeed(0)).pipe(i.flatMap(() => e === "0" ? i.void : d(e))))), f = (e, t, n) => c(e, t).pipe(i.flatMap((t) => n !== void 0 && n > 0 ? s("set", e, (r) => r.psetex(a(e), Math.ceil(n), t)) : s("set", e, (n) => n.set(a(e), t))), i.asVoid);
125
+ return {
126
+ get: (e) => s("get", e, (t) => t.get(a(e))).pipe(i.flatMap((t) => t === null ? i.succeed(l.none()) : u(e, t))),
127
+ set: (e, t, n) => f(e, t, n?.ttlMs),
128
+ setWithTags: (t, n, r) => f(t, n, r.ttlMs).pipe(i.flatMap(() => {
129
+ let n = r.tags ?? [];
130
+ if (n.length === 0) return i.void;
131
+ let a = r.ttlMs !== void 0 && r.ttlMs > 0 ? Math.ceil(r.ttlMs) : -1;
132
+ return e.currentTimeMillis.pipe(i.flatMap((e) => i.forEach(n, (n) => s("setWithTags", t, (r) => r.eval(M, 1, o(n), a, e, t)), { discard: !0 })));
133
+ })),
134
+ remove: (e) => s("remove", e, (t) => t.del([a(e)])).pipe(i.map((e) => e > 0)),
135
+ has: (e) => s("has", e, (t) => t.exists(a(e))).pipe(i.map((e) => e > 0)),
136
+ clear: () => d("0"),
137
+ invalidateTag: (e) => s("invalidateTag", e, (t) => t.zrange(o(e))).pipe(i.flatMap((t) => s("invalidateTag", e, async (n) => {
138
+ let r = t.map(a), i = r.length > 0 ? await n.del(r) : 0;
139
+ return await n.del([o(e)]), i;
140
+ })))
141
+ };
142
+ }), P = (e) => s.scoped(x, N(e)), F = (e) => typeof e == "object" && !!e && e._voltroSwr === 1, I = class extends i.Service()("@voltro/Cache", { effect: i.gen(function* () {
143
+ let t = yield* x, n = yield* h.make(a.empty()), o = c.counter("voltro_cache_hits"), s = c.counter("voltro_cache_misses"), u = (n, r, a) => {
144
+ let o = a.tags === void 0 ? {} : { tags: a.tags }, s = a.swrMs;
145
+ if (s !== void 0) {
146
+ let c = a.ttlMs ?? 0;
147
+ return e.currentTimeMillis.pipe(i.flatMap((e) => t.setWithTags(n, {
148
+ _voltroSwr: 1,
149
+ v: r,
150
+ freshUntil: e + c
151
+ }, {
152
+ ttlMs: c + s,
153
+ ...o
154
+ })));
155
+ }
156
+ let c = a.ttlMs === void 0 ? {} : { ttlMs: a.ttlMs };
157
+ return t.setWithTags(n, r, {
158
+ ...c,
159
+ ...o
160
+ });
161
+ }, d = (e, t, n) => n.pipe(i.tap((n) => u(e, n, t))), f = (e, t) => h.modifyEffect(n, (t) => {
162
+ let n = a.get(t, e);
163
+ return l.isSome(n) ? i.succeed([{
164
+ kind: "await",
165
+ deferred: n.value
166
+ }, t]) : r.make().pipe(i.map((n) => [{
167
+ kind: "own",
168
+ deferred: n
169
+ }, a.set(t, e, n)]));
170
+ }).pipe(i.flatMap((o) => {
171
+ if (o.kind === "await") return r.await(o.deferred);
172
+ let s = o.deferred;
173
+ return t.pipe(i.onExit((t) => r.done(s, t).pipe(i.zipRight(h.update(n, (t) => a.remove(t, e))))));
174
+ })), p = (n, r, a) => t.get(n).pipe(i.flatMap((t) => {
175
+ if (l.isSome(t)) {
176
+ let s = t.value;
177
+ return F(s) ? c.increment(o).pipe(i.zipRight(e.currentTimeMillis), i.flatMap((e) => {
178
+ if (e < s.freshUntil) return i.succeed(s.v);
179
+ let t = f(n, d(n, r, a)).pipe(i.catchAllCause(() => i.void));
180
+ return i.forkDaemon(t).pipe(i.as(s.v));
181
+ })) : c.increment(o).pipe(i.as(s));
182
+ }
183
+ return c.increment(s).pipe(i.zipRight(f(n, d(n, r, a))));
184
+ }));
185
+ return {
186
+ get: (e) => t.get(e),
187
+ set: (e, n, r) => t.set(e, n, r),
188
+ setWithTags: (e, n, r) => t.setWithTags(e, n, r),
189
+ put: (e, t, n) => u(e, n, t),
190
+ remove: t.remove,
191
+ has: t.has,
192
+ clear: t.clear,
193
+ invalidateTag: t.invalidateTag,
194
+ wrap: p,
195
+ partition: (e, n = {}) => {
196
+ let r = (t) => `${e}:${t}`, i = (e) => ({
197
+ ...n.ttlMs === void 0 ? {} : { ttlMs: n.ttlMs },
198
+ ...n.swrMs === void 0 ? {} : { swrMs: n.swrMs },
199
+ ...n.tags === void 0 ? {} : { tags: n.tags },
200
+ ...e
201
+ });
202
+ return {
203
+ get: (e) => t.get(r(e)),
204
+ set: (e, i, a) => t.set(r(e), i, a ?? (n.ttlMs === void 0 ? void 0 : { ttlMs: n.ttlMs })),
205
+ has: (e) => t.has(r(e)),
206
+ remove: (e) => t.remove(r(e)),
207
+ wrap: (e, t, n) => p(r(e), i(t), n),
208
+ invalidateTag: (e) => t.invalidateTag(e)
209
+ };
210
+ },
211
+ stats: () => i.all({
212
+ hits: c.value(o),
213
+ misses: c.value(s)
214
+ }).pipe(i.map(({ hits: e, misses: t }) => {
215
+ let n = Number(e.count), r = Number(t.count), i = n + r;
216
+ return {
217
+ hits: n,
218
+ misses: r,
219
+ hitRate: i === 0 ? 0 : n / i
220
+ };
221
+ }))
222
+ };
223
+ }) }) {}, L = class extends i.Service()("@voltro/InvalidationBus", { scoped: i.gen(function* () {
224
+ let e = yield* u.unbounded(), t = yield* i.scope;
225
+ return {
226
+ publish: (t) => u.publish(e, t).pipe(i.asVoid),
227
+ changes: m.fromPubSub(e),
228
+ addSink: (n) => p.extend(u.subscribe(e), t).pipe(i.flatMap((e) => m.fromQueue(e).pipe(m.runForEach((e) => n(e).pipe(i.ignore)), i.forkIn(t))), i.asVoid)
229
+ };
230
+ }) }) {}, R = /* @__PURE__ */ y({ layer: () => V }), z = i.gen(function* () {
231
+ let e = yield* t.integer("CACHE_MAX_ENTRIES").pipe(t.option), n = l.isSome(e) ? { maxEntries: e.value } : {};
232
+ return I.Default.pipe(s.provide(A(n)));
233
+ }), B = i.gen(function* () {
234
+ let e = yield* t.string("CACHE_REDIS_URL").pipe(t.orElse(() => t.string("REDIS_URL"))), n = yield* t.literal("resp", "http")("CACHE_REDIS_DRIVER").pipe(t.withDefault("resp")), r = yield* t.string("CACHE_REDIS_TOKEN").pipe(t.orElse(() => t.string("UPSTASH_REDIS_REST_TOKEN")), t.option), i = yield* t.string("CACHE_KEY_PREFIX").pipe(t.option), a = {
235
+ driver: n,
236
+ url: e,
237
+ ...l.isSome(r) ? { token: r.value } : {},
238
+ ...l.isSome(i) ? { keyPrefix: i.value } : {}
239
+ };
240
+ return I.Default.pipe(s.provide(P(a)));
241
+ }), V = s.unwrapEffect(i.gen(function* () {
242
+ return (yield* t.literal("memory", "redis")("CACHE_BACKEND").pipe(t.withDefault("memory"))) === "redis" ? yield* B : yield* z;
243
+ }));
244
+ //#endregion
245
+ export { I as Cache, b as CacheError, R as CacheLayer, x as CacheStore, L as InvalidationBus, A as layerMemory, P as layerRedis };
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@voltro/cache",
3
+ "version": "0.1.0",
4
+ "description": "Effect-native cache primitive — memory + RESP (Redis/Valkey/KeyDB/Dragonfly/Upstash) backends, tag invalidation, single-flight wrap.",
5
+ "keywords": [
6
+ "voltro",
7
+ "typescript",
8
+ "framework"
9
+ ],
10
+ "license": "SEE LICENSE IN LICENSE",
11
+ "homepage": "https://voltro.dev",
12
+ "bugs": {
13
+ "email": "support@voltro.dev"
14
+ },
15
+ "author": {
16
+ "name": "Voltro UG",
17
+ "url": "https://voltro.dev"
18
+ },
19
+ "type": "module",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./dist/index.d.ts",
23
+ "import": "./dist/index.js",
24
+ "default": "./dist/index.js"
25
+ }
26
+ },
27
+ "main": "./dist/index.js",
28
+ "module": "./dist/index.js",
29
+ "types": "./dist/index.d.ts",
30
+ "sideEffects": false,
31
+ "engines": {
32
+ "node": ">=24.0.0"
33
+ },
34
+ "dependencies": {
35
+ "@voltro/kv": "0.1.0"
36
+ },
37
+ "peerDependencies": {
38
+ "effect": "^3.21.4"
39
+ },
40
+ "publishConfig": {
41
+ "access": "public"
42
+ }
43
+ }