@mark1russell7/stack-spend 0.0.0-bootstrap.0 → 0.1.5

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Russell
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,473 @@
1
1
  # @mark1russell7/stack-spend
2
2
 
3
- This version is a placeholder. The release workflow of https://github.com/mark1russell7/system-stack publishes the real versions. Use a later version.
3
+ The cost of each part of a system stack as data: plans, prices and the limits of the cost of a month. The package has a gate that fails when a cost can grow with no hard limit. A second gate compares the used amount of a month with each limit. A plan that ends on a date gives a warning before the date, and a query tells which parts stop.
4
+
5
+ It is the spend add-on of [`@mark1russell7/system-stack`](../system-stack/README.md). The core knows only parts and needs. This package puts a cost record on a part.
6
+
7
+ Each function is a plain function with no clock and no network. Each formula is a Vex program.
8
+
9
+ ## The rule
10
+
11
+ A cost that grows with the use must have a hard limit for a month. A limit is hard when something stops the use at the amount:
12
+
13
+ | Kind of limit | What stops the use | Hard |
14
+ | --- | --- | --- |
15
+ | `provider` | The provider stops the service at the amount. | Yes |
16
+ | `prepaid` | The provider stops the service when the prepaid balance is empty. | Yes, with no automatic recharge |
17
+ | `code` | A part of the stack counts the cost and stops the use at the amount. | Yes |
18
+ | `alert` | Nothing. A message comes at the amount. | No |
19
+
20
+ An alert stops nothing, so an alert is not a limit. A balance that gets money automatically is not a limit.
21
+
22
+ ## The entries
23
+
24
+ | Entry | What it has |
25
+ | --- | --- |
26
+ | `@mark1russell7/stack-spend` | The records of a layer, the cost formulas, the states, the gate, the steps of the owner, the used amounts and a sample. |
27
+ | `@mark1russell7/stack-spend/schema` | `spendSchema` and `parseSpend` for a layer, and `readsSchema` and `parseReads` for a list of reads. |
28
+ | `@mark1russell7/stack-spend/add-on` | `spendAddOn`, the add-on in the form of the layer contract of the core. |
29
+
30
+ The root entry has no schema library. Thus a page that only shows the cost of a month gets no zod.
31
+
32
+ ## Install
33
+
34
+ ```sh
35
+ npm install @mark1russell7/stack-spend @mark1russell7/system-stack
36
+ ```
37
+
38
+ ## A layer
39
+
40
+ A spend layer is one record with a list of cost records. Its format has the name `spend/1`. A stack keeps it in `Stack.layers`, with the key `spend/1`.
41
+
42
+ ```ts
43
+ import type { SpendLayer } from "@mark1russell7/stack-spend";
44
+
45
+ const layer: SpendLayer = {
46
+ schema: "spend/1",
47
+ currency: "USD",
48
+ kinds: ["account"],
49
+ proofDays: 90,
50
+ services: [
51
+ {
52
+ part: "cloud-account",
53
+ plan: "A free allowance, then a price for the use",
54
+ billing: "metered",
55
+ limits: [{ kind: "alert", amount: 5 }],
56
+ proof: { date: "2026-11-10", by: "The owner", source: "The billing page of the account" },
57
+ },
58
+ {
59
+ part: "push-account",
60
+ plan: "A license that was paid one time",
61
+ billing: "fixed",
62
+ price: 0,
63
+ proof: { date: "2026-11-10", by: "The owner", source: "The license page of the account" },
64
+ },
65
+ {
66
+ part: "call-account",
67
+ plan: "A price for each call",
68
+ billing: "metered",
69
+ limits: [
70
+ { kind: "prepaid", amount: 20, recharge: true },
71
+ { kind: "code", amount: 10, stop: "program-home" },
72
+ ],
73
+ proof: { date: "2026-11-10", by: "The owner", source: "The billing page of the account" },
74
+ steps: ["Open the billing page of the account.", "Stop the automatic recharge.", "Save the change."],
75
+ },
76
+ ],
77
+ };
78
+ ```
79
+
80
+ This layer is `SAMPLE_SPEND` of the package. It is for `SAMPLE_STACK` of the core.
81
+
82
+ | Field of the layer | What it is |
83
+ | --- | --- |
84
+ | `currency` | The currency of each amount, as a code of ISO 4217. |
85
+ | `kinds` | The kinds of the parts that can have a cost. Each part of one of these kinds must have a record. |
86
+ | `proofDays` | The largest age of a proof, in days. |
87
+ | `endDays` | The count of days before the end of a plan from which the gate gives a warning. The default is 30. |
88
+ | `services` | The cost records, one for each part. |
89
+
90
+ | Field of a cost record | What it is |
91
+ | --- | --- |
92
+ | `part` | The `id` of the part of the stack with the cost. |
93
+ | `plan` | The name of the plan. |
94
+ | `billing` | `free`, `fixed` or `metered`. |
95
+ | `price` | The fixed price of a month. A `fixed` service must have one. |
96
+ | `limits` | The limits that are in force. Each limit has a `kind` and an `amount` for a month. |
97
+ | `wanted` | A limit that is not in force. The gate fails until the limit is in `limits`. |
98
+ | `ends` | The end of the plan, for a plan that ends on a date. Refer to [The end of a plan](#the-end-of-a-plan). |
99
+ | `proof` | The read of the account: its `date`, its reader in `by`, and its `source`. |
100
+ | `steps` | The steps of the owner in the account of the service. |
101
+
102
+ The billing tells if the cost can grow:
103
+
104
+ - `free`: the provider cannot take money. The account has no payment method, or the plan has no paid use.
105
+ - `fixed`: the price of a month is fixed. A price that was paid one time is a fixed price of 0.
106
+ - `metered`: the cost grows with the use. A free allowance with a payment method on the account is `metered`.
107
+
108
+ A limit of the kind `prepaid` can have `recharge: true`: the provider adds money automatically. A limit of the kind `code` names in `stop` the part of the stack that stops the use.
109
+
110
+ ## The gate
111
+
112
+ `checkSpend(layer, stack, { today })` gives the faults of a layer. A list with no error tells that the gate passes. A warning does not stop the gate. The gate has no clock: the caller gives the date.
113
+
114
+ ```ts
115
+ import { checkSpend, SAMPLE_SPEND, SAMPLE_TODAY } from "@mark1russell7/stack-spend";
116
+ import { SAMPLE_STACK } from "@mark1russell7/system-stack";
117
+
118
+ checkSpend(SAMPLE_SPEND, SAMPLE_STACK, { today: SAMPLE_TODAY }).map((fault) => `${fault.code}: ${fault.message}`);
119
+ // => [
120
+ // 'limit-alert: The cost of "cloud-account" grows with the use, and its only limit is an alert. An alert stops nothing.',
121
+ // 'limit-recharge: The prepaid balance of "call-account" gets money automatically, so it does not limit the cost.',
122
+ // ]
123
+ ```
124
+
125
+ | Code | Level | The fault |
126
+ | --- | --- | --- |
127
+ | `service-part` | error | A record names no part of the stack. |
128
+ | `service-duplicate` | error | Two records name one part. |
129
+ | `part-no-service` | error | A part of a kind of `kinds` has no record. |
130
+ | `price` | error | A price is less than 0 or not finite, or a `fixed` plan has no price. |
131
+ | `amount` | error | The amount of a limit is less than 0 or not finite. |
132
+ | `limit-none` | error | The cost of a `metered` service has no limit. |
133
+ | `limit-alert` | error | The only limits of a `metered` service are alerts. |
134
+ | `limit-recharge` | error | A prepaid balance gets money automatically. |
135
+ | `limit-stop` | error | A stop by code does not name the part of the stack that stops the use. |
136
+ | `limit-wanted` | error | A wanted limit is not in force. |
137
+ | `end-date` | error | The date of the end of a plan is not a date. |
138
+ | `end-past` | error | The plan ended before the date of the check. The record gives the cost before the end. |
139
+ | `end-soon` | warning | The plan ends in `endDays` days, or fewer. |
140
+ | `end-open` | error | The cost after the end of a plan grows with the use, and it has no hard limit. |
141
+ | `proof-none` | error | A record has no proof. |
142
+ | `proof-date` | error | The date of a proof is not a date, or it is after the date of the check. |
143
+ | `proof-old` | error | A proof is older than `proofDays`. |
144
+
145
+ A record with no cost needs a proof too. Thus "this service is free" is a statement with a reader and a date, and it becomes old.
146
+
147
+ ## The end of a plan
148
+
149
+ A trial, a free credit or a term ends on a date. The field `ends` of a cost record gives that date. The fields `billing`, `price` and `limits` of the record give the cost before the end.
150
+
151
+ | Field of `ends` | What it is |
152
+ | --- | --- |
153
+ | `date` | The last day of the plan, as `YYYY-MM-DD`. |
154
+ | `next` | The cost after the end: its `plan`, its `billing`, its `price` and its `limits`. A service that stops has none. |
155
+
156
+ - With no `next`, the provider stops the service after the date, and it takes no money. The part does not work after the date.
157
+ - With a `next`, the service continues after the date, with the cost of `next`.
158
+ - The rule holds for the cost of `next` too: a `metered` cost must have a hard limit.
159
+
160
+ `SAMPLE_ENDS` of the package is a layer for `SAMPLE_STACK` with two plans that end:
161
+
162
+ ```ts
163
+ const proof = { date: "2026-11-10", by: "The owner", source: "The billing page of the account" };
164
+ const services = [
165
+ {
166
+ part: "cloud-account",
167
+ plan: "A free trial",
168
+ billing: "free",
169
+ ends: { date: "2026-12-01", next: { plan: "A price for the use", billing: "metered", limits: [{ kind: "alert", amount: 5 }] } },
170
+ proof,
171
+ },
172
+ {
173
+ part: "call-account",
174
+ plan: "A free credit, with no payment method",
175
+ billing: "free",
176
+ ends: { date: "2026-11-30" },
177
+ proof,
178
+ },
179
+ ];
180
+ ```
181
+
182
+ ```ts
183
+ import { checkSpend, SAMPLE_ENDS, SAMPLE_TODAY } from "@mark1russell7/stack-spend";
184
+ import { SAMPLE_STACK } from "@mark1russell7/system-stack";
185
+
186
+ checkSpend(SAMPLE_ENDS, SAMPLE_STACK, { today: SAMPLE_TODAY }).map((fault) => `${fault.level} ${fault.code}: ${fault.message}`);
187
+ // => [
188
+ // 'warning end-soon: The plan of "cloud-account" ends on 2026-12-01, in 15 days. Then the cost changes.',
189
+ // 'error end-open: The plan of "cloud-account" ends on 2026-12-01. After the end, the cost grows with the use, and it has no hard limit.',
190
+ // 'warning end-soon: The plan of "call-account" ends on 2026-11-30, in 14 days. Then the provider stops the service.',
191
+ // ]
192
+ ```
193
+
194
+ The free trial of the cloud account becomes a cost with no hard limit. Thus the gate fails before the first invoice, not after it.
195
+ The free credit of the call account ends with no plan after it. The provider takes no money, so the gate gives only a warning.
196
+
197
+ - The warning starts `endDays` days before the last day of the plan. The default is `END_DAYS`, 30 days.
198
+ - After the last day, the fault is `end-past`: the record gives the old plan. The owner reads the account again.
199
+ - A plan that ends later than the days of warning gives no fault. The fault `end-open` does not wait for the days of warning.
200
+ - The faults `price`, `amount` and `limit-stop` examine the cost of `next` too.
201
+
202
+ ### The parts that stop
203
+
204
+ `planEnds(layer, { today })` gives the end of each plan, with the nearest date first. `endStops(layer, stack, { today })` gives the parts of the stack that stop.
205
+
206
+ ```ts
207
+ import { endStops, planEnds, SAMPLE_ENDS, SAMPLE_TODAY } from "@mark1russell7/stack-spend";
208
+ import { SAMPLE_STACK } from "@mark1russell7/system-stack";
209
+
210
+ planEnds(SAMPLE_ENDS, { today: SAMPLE_TODAY });
211
+ // => [
212
+ // { part: "call-account", date: "2026-11-30", days: 14, stops: true },
213
+ // { part: "cloud-account", date: "2026-12-01", days: 15, stops: false },
214
+ // ]
215
+
216
+ endStops(SAMPLE_ENDS, SAMPLE_STACK, { today: SAMPLE_TODAY });
217
+ // => { ended: ["call-account"], stopped: ["call-account", "call"] }
218
+ ```
219
+
220
+ - `ended` has each service that its provider stops in the days of warning. A plan that ended before the date of the check is in it too.
221
+ - `stopped` has each part of the stack that does not work without the parts of `ended`. It comes from the needs of the stack.
222
+ - A service with a `next` does not stop, so it is not in `ended`.
223
+ - The option `days` gives a different count of days. For the parts that stop with one service, use `stopped` of the core.
224
+
225
+ In the sample, the call service stops with its account. The alert still works, because it gets to its reader through the push service.
226
+
227
+ The answer is as complete as the needs of the stack. Make a key of an account a part that needs the account. Make each program that uses the key a part that needs the key. Then `stopped` has each program that stops.
228
+
229
+ ## The largest cost of a month
230
+
231
+ `serviceStates(layer)` gives the hard limit and the largest cost of each service. `monthTotal(layer)` gives the largest cost of the layer.
232
+
233
+ ```ts
234
+ import { monthTotal, SAMPLE_SPEND, serviceStates } from "@mark1russell7/stack-spend";
235
+
236
+ serviceStates(SAMPLE_SPEND);
237
+ // => [
238
+ // { part: "cloud-account", billing: "metered" },
239
+ // { part: "push-account", billing: "fixed", monthMax: 0 },
240
+ // { part: "call-account", billing: "metered", hardLimit: 10, monthMax: 10 },
241
+ // ]
242
+
243
+ monthTotal(SAMPLE_SPEND);
244
+ // => { bounded: 10, open: ["cloud-account"] }
245
+ ```
246
+
247
+ - The largest cost of a `free` service is 0, and that of a `fixed` service is its price.
248
+ - The largest cost of a `metered` service is its price plus its hard limit. The hard limit is the smallest amount of its hard limits.
249
+ - A service with no bound has no `monthMax`. Its part is in `open` of the total.
250
+ - For a plan that ends, the largest cost is the larger of the cost before the end and the cost after it. `nextLimit` is the hard limit after the end.
251
+ - A cost with no bound after the end gives no `monthMax`, also when the plan before the end is free.
252
+
253
+ The cost of the layer has a bound only when `open` is empty. Then `bounded` is that bound.
254
+
255
+ ## The steps of the owner
256
+
257
+ A program cannot change the settings of an account. `ownerSteps(layer, stack, { today })` gives the work of the owner of the accounts, from the faults of the gate.
258
+
259
+ ```ts
260
+ import { ownerSteps, SAMPLE_SPEND, SAMPLE_TODAY } from "@mark1russell7/stack-spend";
261
+ import { SAMPLE_STACK } from "@mark1russell7/system-stack";
262
+
263
+ ownerSteps(SAMPLE_SPEND, SAMPLE_STACK, { today: SAMPLE_TODAY });
264
+ // => [{
265
+ // part: "call-account",
266
+ // name: "The account of the call service",
267
+ // code: "limit-recharge",
268
+ // text: "Stop the automatic recharge of the prepaid balance.",
269
+ // steps: ["Open the billing page of the account.", "Stop the automatic recharge.", "Save the change."],
270
+ // }]
271
+ ```
272
+
273
+ | Code | The work of the owner |
274
+ | --- | --- |
275
+ | `limit-wanted` | Set the wanted limit in the account. A wanted stop by code is the work of a programmer, so it gives no step. |
276
+ | `limit-recharge` | Stop the automatic recharge of the balance. |
277
+ | `end-soon` | Decide before the date. A service with no plan after the end stops, and the cost of each other service changes. |
278
+ | `end-open` | Set a hard limit for the cost after the end, or stop the service before the date. Then `end-soon` gives no second step. |
279
+ | `end-past`, `proof-none`, `proof-old` | Read the plan and the limits in the account, and give them with the date of the read. |
280
+
281
+ The alert of the cloud account gives no step, because the records do not tell which limit to set. Add a `wanted` limit to the record. Then the fault is `limit-wanted`, and the owner gets a step.
282
+
283
+ ## The used amount of a month
284
+
285
+ A limit tells the largest cost of a month. A read tells the cost until a date. `useStates(layer, reads, { today })` gives the used amount of each service in the month of `today`.
286
+
287
+ A read is live data, so it is not a record of the layer. A program makes each read, and the functions take a list of reads.
288
+
289
+ | Field of a read | What it is |
290
+ | --- | --- |
291
+ | `part` | The `id` of the part of the service. |
292
+ | `source` | `count` or `provider`. |
293
+ | `amount` | The cost of the use from the start of the month until the read. |
294
+ | `date` | The date of the read. Its month is the month of the amount. |
295
+
296
+ The source tells who gives the amount:
297
+
298
+ - `count`: a part of the stack counted the use, and it gives the cost of that use.
299
+ - `provider`: the provider of the service shows the cost of the use, on a usage page or in a usage API.
300
+
301
+ The rule: the used amount is the larger of the count of the stack and the amount of the provider.
302
+ A stop by code counts its own use. The provider can show more, because a different program used the account, or because a price changed.
303
+ Thus a stop that follows the rule does not stop too late.
304
+
305
+ ```ts
306
+ import { SAMPLE_READS, SAMPLE_SPEND, SAMPLE_TODAY, useStates } from "@mark1russell7/stack-spend";
307
+
308
+ SAMPLE_READS;
309
+ // => [
310
+ // { part: "cloud-account", source: "provider", amount: 0, date: "2026-11-15" },
311
+ // { part: "call-account", source: "count", amount: 4, date: "2026-11-16" },
312
+ // { part: "call-account", source: "provider", amount: 5.2, date: "2026-11-16" },
313
+ // ]
314
+
315
+ useStates(SAMPLE_SPEND, SAMPLE_READS, { today: SAMPLE_TODAY });
316
+ // => [
317
+ // { part: "cloud-account", billing: "metered", provider: 0, used: 0, age: 1 },
318
+ // { part: "push-account", billing: "fixed" },
319
+ // { part: "call-account", billing: "metered", count: 4, provider: 5.2, used: 5.2, limit: 10, share: 0.52, level: 0.5, over: false, age: 0 },
320
+ // ]
321
+ ```
322
+
323
+ | Field of a state | What it is |
324
+ | --- | --- |
325
+ | `count` | The largest amount that a part of the stack counted in the month. |
326
+ | `provider` | The largest amount that the provider showed in the month. |
327
+ | `used` | The used amount: the larger of `count` and `provider`. |
328
+ | `limit` | The hard limit of the service for a month. |
329
+ | `share` | The used share of the hard limit: `used` divided by `limit`. |
330
+ | `level` | The largest level that the share reached. The default levels are 0.5, 0.8 and 1. |
331
+ | `over` | `true` when the used amount is more than the hard limit. |
332
+ | `age` | The age of the newest read of the month, in days. |
333
+
334
+ - A field with no known value is absent. Thus a service with no read of the month has no `used`.
335
+ - The amount of a read is the part of the cost that grows with the use. The fixed price of a plan is not in it.
336
+ - The cost of a month does not go down. Thus the largest read of the month is the used amount, and a smaller read after it changes nothing.
337
+ - A read of a different month does not count.
338
+ - A read with a fault does not count, and the gate tells the fault.
339
+ - The option `levels` gives different levels. Each level is a share of the hard limit, above 0.
340
+
341
+ ### The gate of the used amounts
342
+
343
+ `checkUse(layer, reads, { today })` gives the faults of the used amounts. An error stops the gate. A warning does not.
344
+
345
+ ```ts
346
+ import { checkUse, SAMPLE_READS, SAMPLE_SPEND, SAMPLE_TODAY } from "@mark1russell7/stack-spend";
347
+
348
+ checkUse(SAMPLE_SPEND, SAMPLE_READS, { today: SAMPLE_TODAY }).map((fault) => `${fault.level} ${fault.code}: ${fault.message}`);
349
+ // => [
350
+ // 'warning use-level: The used amount of "call-account" in the month 2026-11 is 5.2 USD: 50 percent of its hard limit of 10 USD, or more.',
351
+ // 'warning use-count: The provider shows 5.2 USD for "call-account" in the month 2026-11, and the stack counted 4 USD. The count does not have all the use.',
352
+ // ]
353
+ ```
354
+
355
+ | Code | Level | The fault |
356
+ | --- | --- | --- |
357
+ | `read-part` | error | A read names a part with no cost record. |
358
+ | `read-amount` | error | The amount of a read is less than 0 or not finite. |
359
+ | `read-date` | error | The date of a read is not a date, or it is after the date of the check. |
360
+ | `use-billing` | error | A read shows a cost of the use of a `free` or `fixed` service. The cost record is not correct. |
361
+ | `use-over` | error | The used amount is more than the hard limit. The limit did not hold. |
362
+ | `use-level` | warning | The used amount reached a level of the hard limit. |
363
+ | `use-count` | warning | The provider shows more than the stack counted. The count does not have all the use. |
364
+ | `use-none` | warning | A `metered` service has no read of the month, so its used amount is not known. |
365
+ | `use-old` | warning | The newest read of a `metered` service is older than the option `readDays`. |
366
+
367
+ - A used amount that is equal to the hard limit is no failure: the limit stopped the use. A used amount above the limit is a failure of the limit.
368
+ - A service with no read does not pass and does not fail. The gate tells that it has no read.
369
+ - The gate has no memory. A host that sends a message at each level keeps the last level that it sent for each service.
370
+ - The option `readDays` gives the largest age of the newest read. With no value, the gate examines no age.
371
+
372
+ ## The formulas
373
+ The layer becomes a tree: the layer, then each service, then each limit in force. The plan after the end of a plan is a child of its service too, with its own limits as children.
374
+ `spendSpace(layer)` gives this tree as a space of Vex. A plan is a service node or the node of a plan after an end. The programs evaluate on the tree:
375
+
376
+ | Program | Where | What it gives |
377
+ | --- | --- | --- |
378
+ | `IS_HARD` | A limit | If the limit is hard. This program is the one definition of a hard limit. |
379
+ | `HARD_COUNT` | A plan | The count of its hard limits. |
380
+ | `HARD_LIMIT` | A plan | The smallest amount of its hard limits. With no hard limit, it gives `#N/A`. |
381
+ | `PLAN_MAX` | A plan | The largest cost of the plan in a month. With no bound, it gives `#N/A`. |
382
+ | `MONTH_MAX` | A service | The largest cost of a month, before the end of its plan or after it. With no bound, it gives `#N/A`. |
383
+ | `BOUNDED_TOTAL` | The layer | The sum of the largest costs of the services that have a bound. |
384
+ | `OPEN_SERVICES` | The layer | The keys of the services with no bound. |
385
+
386
+ A program is data, so a tool can show each step of a result. `evaluateService(program, tree, part)` evaluates a program at one service. `evaluateNext(program, tree, part)` evaluates a program at the plan after the end of the plan of a service.
387
+
388
+ The reads become a second tree: the layer, then each service, then each read. `useSpace(layer, reads, { today })` gives this tree. These programs evaluate at a service of it:
389
+
390
+ | Program | What it gives |
391
+ | --- | --- |
392
+ | `COUNT_USED` | The largest amount of the reads of the source `count` in the month. |
393
+ | `PROVIDER_USED` | The largest amount of the reads of the source `provider` in the month. |
394
+ | `USED` | The used amount: the largest amount of the reads of the month. This program is the one definition of the rule. |
395
+ | `USE_SHARE` | The used amount divided by the hard limit. |
396
+ | `USE_OVER` | If the used amount is more than the hard limit. |
397
+ | `USE_LEVEL` | The largest level that the share reached. A share below each level gives 0. |
398
+ | `READ_AGE` | The age of the newest read of the month, in days. |
399
+
400
+ `MONTH_READS` is the axis of the reads of a service in the month of the check.
401
+ A share reaches a level when it is the level less `LEVEL_TOLERANCE`, or more. Thus the rounding of a division does not hide a level.
402
+
403
+ ## The read of JSON
404
+
405
+ `parseSpend` of the entry `/schema` reads the JSON of a layer. It gives the layer, or the faults of its form with the place of each fault.
406
+
407
+ ```ts
408
+ import { parseSpend } from "@mark1russell7/stack-spend/schema";
409
+
410
+ parseSpend({ schema: "spend/1", currency: "USD", kinds: [], proofDays: 90, services: [{ part: "a", billing: "paid" }] });
411
+ // => { ok: false, errors: ['The record "spend/1" has a fault at "services.0.billing": Invalid option: expected one of "free"|"fixed"|"metered"'] }
412
+ ```
413
+
414
+ The schema examines the form of a record. `checkSpend` examines the meaning of a layer with a correct form.
415
+
416
+ `parseReads` reads the JSON of a list of reads in the same way, and `checkUse` examines the meaning of the reads.
417
+
418
+ ## The cost records of some owners
419
+
420
+ `joinSpend(pieces)` joins the spend layers of the fragments of a stack into one layer. A piece is the layer of one fragment, with the name of the fragment.
421
+
422
+ - The cost records are in the order of the fragments. The record of a part is in one fragment.
423
+ - A part with a record in two or more fragments is a fault. Equal records give the fault too.
424
+ - The layer has one `currency` and one `proofDays`. A fragment with a different value is a fault.
425
+ - The layer has one `endDays` too. A fragment with no `endDays` takes the value of the other fragments.
426
+ - The `kinds` are the kinds of each fragment, one time each.
427
+
428
+ The kinds of the joined layer hold for each part of the joined stack. Thus a kind of one fragment asks a cost record of the parts of that kind in each fragment.
429
+
430
+ ```ts
431
+ import { joinSpend } from "@mark1russell7/stack-spend";
432
+
433
+ const proof = { date: "2026-11-10", by: "The owner" };
434
+ const shared = { schema: "spend/1", currency: "USD", proofDays: 90 } as const;
435
+
436
+ joinSpend([
437
+ { from: "a.json", layer: { ...shared, kinds: ["account"], services: [{ part: "one", billing: "free", proof }] } },
438
+ { from: "b.json", layer: { ...shared, kinds: ["account", "license"], services: [{ part: "two", billing: "free", proof }] } },
439
+ ]);
440
+ // => { ok: true, layer: { schema: "spend/1", currency: "USD", kinds: ["account", "license"], proofDays: 90, services: [{ part: "one", ... }, { part: "two", ... }] } }
441
+
442
+ joinSpend([
443
+ { from: "a.json", layer: { ...shared, kinds: ["account"], services: [{ part: "one", billing: "free", proof }] } },
444
+ { from: "b.json", layer: { ...shared, currency: "EUR", proofDays: 30, kinds: ["account"], services: [{ part: "one", billing: "free", proof }] } },
445
+ ]);
446
+ // => {
447
+ // ok: false,
448
+ // errors: [
449
+ // 'The fragment "a.json" has the currency "USD", and the fragment "b.json" has "EUR".',
450
+ // 'The fragment "a.json" has the largest age of a proof in days 90, and the fragment "b.json" has 30.',
451
+ // 'The fragments "a.json", "b.json" each have the cost record of the part "one".',
452
+ // ],
453
+ // }
454
+ ```
455
+
456
+ The add-on of the entry `/add-on` has the function as `join`. `joinStacks` of the core uses it for a stack in two or more documents, and the gate `checkSpend` examines the joined layer afterward.
457
+
458
+ ## The add-on for one check of a stack
459
+
460
+ `spendAddOn` of the entry `/add-on` gives the add-on in the form of the layer contract. A host gives it to `checkStackLayers` of the core, with the add-ons of the other layers. A host with a stack in two or more documents gives it to `joinStacks` first.
461
+
462
+ ```ts
463
+ import { spendAddOn } from "@mark1russell7/stack-spend/add-on";
464
+ import { checkStackLayers } from "@mark1russell7/system-stack";
465
+
466
+ checkStackLayers(stack, [spendAddOn({ today: "2026-11-16" })]);
467
+ // => the faults of the stack, then the faults of `checkSpend` for the layer `spend/1`, each with the name of its layer
468
+ ```
469
+
470
+ A layer with a wrong form gives one finding `layer-form` for each fault of the form, and the gate does not start. The function refuses a date of a wrong form at once, with a `RangeError`.
471
+
472
+ ## License
473
+ MIT
@@ -0,0 +1,16 @@
1
+ import { i as SpendOptions } from "./check-CpHvgGvh.js";
2
+ import { f as SpendLayer } from "./layer-BYSJfC_1.js";
3
+ import { StackJoiner } from "@mark1russell7/system-stack";
4
+ /**
5
+ * This function gives the spend add-on for a check on one date.
6
+ *
7
+ * - `schema` is `spend/1`, the key of the layer in `Stack.layers`.
8
+ * - `parse` is `parseSpend`.
9
+ * - `check` is the gate `checkSpend` with the options.
10
+ * - `join` is `joinSpend`. It joins the spend layers of the fragments of a stack.
11
+ *
12
+ * @param options - The options of the gate. The gate has no clock: the caller gives the date.
13
+ * @throws RangeError when `today` is not a date `YYYY-MM-DD`
14
+ */
15
+ export declare function spendAddOn(options: SpendOptions): StackJoiner<SpendLayer>;
16
+ //# sourceMappingURL=add-on.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"add-on.d.ts","names":[],"sources":["../src/add-on.ts"],"mappings":";;;;;;;;;;;;;;wBAoBgB,WAAW,SAAS,eAAe,YAAY"}
@@ -0,0 +1,28 @@
1
+ import { r as checkSpend, t as joinSpend } from "./join-BsjQ9eKd.js";
2
+ import { o as SPEND_SCHEMA } from "./reads-BNyUIVaY.js";
3
+ import { parseSpend } from "./schema.js";
4
+ import { dayNumber } from "@mark1russell7/system-stack";
5
+ // src/add-on.ts
6
+ /**
7
+ * This function gives the spend add-on for a check on one date.
8
+ *
9
+ * - `schema` is `spend/1`, the key of the layer in `Stack.layers`.
10
+ * - `parse` is `parseSpend`.
11
+ * - `check` is the gate `checkSpend` with the options.
12
+ * - `join` is `joinSpend`. It joins the spend layers of the fragments of a stack.
13
+ *
14
+ * @param options - The options of the gate. The gate has no clock: the caller gives the date.
15
+ * @throws RangeError when `today` is not a date `YYYY-MM-DD`
16
+ */
17
+ function spendAddOn(options) {
18
+ if (dayNumber(options.today) === void 0) throw new RangeError(`The date "${options.today}" is not a date of the form YYYY-MM-DD.`);
19
+ return {
20
+ schema: SPEND_SCHEMA,
21
+ parse: parseSpend,
22
+ check: (layer, stack) => checkSpend(layer, stack, options),
23
+ join: joinSpend
24
+ };
25
+ }
26
+ export { spendAddOn };
27
+
28
+ //# sourceMappingURL=add-on.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"add-on.js","names":[],"sources":["../src/add-on.ts"],"sourcesContent":["import { dayNumber, type StackJoiner } from \"@mark1russell7/system-stack\";\nimport { checkSpend, type SpendOptions } from \"./check.ts\";\nimport { joinSpend } from \"./join.ts\";\nimport { SPEND_SCHEMA, type SpendLayer } from \"./layer.ts\";\nimport { parseSpend } from \"./schema.ts\";\n\n// The spend add-on in the form of the layer contract. A host gives it to `checkStackLayers` and to `joinStacks` of the core.\n// This entry has the schema library, so the root entry does not import it.\n\n/**\n * This function gives the spend add-on for a check on one date.\n *\n * - `schema` is `spend/1`, the key of the layer in `Stack.layers`.\n * - `parse` is `parseSpend`.\n * - `check` is the gate `checkSpend` with the options.\n * - `join` is `joinSpend`. It joins the spend layers of the fragments of a stack.\n *\n * @param options - The options of the gate. The gate has no clock: the caller gives the date.\n * @throws RangeError when `today` is not a date `YYYY-MM-DD`\n */\nexport function spendAddOn(options: SpendOptions): StackJoiner<SpendLayer> {\n if (dayNumber(options.today) === undefined) throw new RangeError(`The date \"${options.today}\" is not a date of the form YYYY-MM-DD.`);\n return { schema: SPEND_SCHEMA, parse: parseSpend, check: (layer, stack) => checkSpend(layer, stack, options), join: joinSpend };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoBA,SAAgB,WAAW,SAAgD;CACzE,IAAI,UAAU,QAAQ,KAAK,MAAM,KAAA,GAAW,MAAM,IAAI,WAAW,aAAa,QAAQ,MAAM,wCAAwC;CACpI,OAAO;EAAE,QAAQ;EAAc,OAAO;EAAY,QAAQ,OAAO,UAAU,WAAW,OAAO,OAAO,OAAO;EAAG,MAAM;CAAU;AAChI"}
@@ -0,0 +1,51 @@
1
+ import { f as SpendLayer } from "./layer-BYSJfC_1.js";
2
+ import { Fault, Stack, dayNumber } from "@mark1russell7/system-stack";
3
+ /** These are the codes of the faults of a spend layer. */
4
+ declare const SPEND_CODES: readonly ["service-part", "service-duplicate", "part-no-service", "price", "amount", "limit-none", "limit-alert", "limit-recharge", "limit-stop", "limit-wanted", "end-date", "end-past", "end-soon", "end-open", "proof-none", "proof-date", "proof-old"];
5
+ /** A code of a fault of a spend layer. */
6
+ type SpendCode = (typeof SPEND_CODES)[number];
7
+ /** A fault of a spend layer. Its field `at` is the `id` of the part. */
8
+ interface SpendFault extends Fault {
9
+ readonly code: SpendCode;
10
+ }
11
+ /** The options of the gate. */
12
+ interface SpendOptions {
13
+ /** The date of the check, as `YYYY-MM-DD`. The gate has no clock: the caller gives the date. */
14
+ readonly today: string;
15
+ }
16
+ /**
17
+ * This function gives each fault of a spend layer for a stack. A list with no error tells that the gate passes.
18
+ *
19
+ * The records:
20
+ * - `service-part`: a record names no part of the stack.
21
+ * - `service-duplicate`: two records name one part.
22
+ * - `part-no-service`: a part of a kind of `kinds` has no record.
23
+ * - `price`: a price is less than 0 or not finite, or a `fixed` plan has no price.
24
+ * - `amount`: the amount of a limit is less than 0 or not finite.
25
+ *
26
+ * The limits:
27
+ * - `limit-none`: the cost of a `metered` service has no limit.
28
+ * - `limit-alert`: the only limits of a `metered` service are alerts. An alert stops nothing.
29
+ * - `limit-recharge`: a prepaid balance gets money automatically, so it is no limit.
30
+ * - `limit-stop`: a stop by code does not name the part of the stack that stops the use.
31
+ * - `limit-wanted`: a wanted limit is not in force.
32
+ *
33
+ * The end of a plan:
34
+ * - `end-date`: the date of an end is not a date.
35
+ * - `end-past`: the plan ended before `today`. The record gives the cost before the end, so it is not correct.
36
+ * - `end-soon`: the plan ends in `endDays` days, or fewer. This fault is a warning: it does not stop the gate.
37
+ * - `end-open`: the cost after the end grows with the use, and it has no hard limit.
38
+ *
39
+ * The proofs:
40
+ * - `proof-none`: a record has no proof.
41
+ * - `proof-date`: the date of a proof is not a date, or it is after `today`.
42
+ * - `proof-old`: a proof is older than `proofDays`.
43
+ *
44
+ * The faults `price`, `amount` and `limit-stop` examine the plan after an end too.
45
+ * The faults are in the sequence of the records, then of the parts with no record. The function is pure.
46
+ *
47
+ * @throws RangeError when `today` is not a date `YYYY-MM-DD`
48
+ */
49
+ declare function checkSpend(layer: SpendLayer, stack: Stack, options: SpendOptions): SpendFault[];
50
+ export { checkSpend as a, SpendOptions as i, SpendCode as n, dayNumber as o, SpendFault as r, SPEND_CODES as t };
51
+ //# sourceMappingURL=check-CpHvgGvh.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"check-CpHvgGvh.d.ts","names":[],"sources":["../src/check.ts"],"mappings":";;;cAOa;;KAuCD,oBAAoB;;UAGf,mBAAmB;WACzB,MAAM;;;UAIA;;WAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkDK,WAAW,OAAO,YAAY,OAAO,OAAO,SAAS,eAAe"}