@intellectual-frontiers/formats 0.0.0-stage → 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 (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +8 -2
  3. package/dist/archive.d.ts +147 -0
  4. package/dist/archive.js +765 -0
  5. package/dist/base64.d.ts +24 -0
  6. package/dist/base64.js +52 -0
  7. package/dist/cbor.d.ts +39 -0
  8. package/dist/cbor.js +244 -0
  9. package/dist/csv.d.ts +38 -0
  10. package/dist/csv.js +130 -0
  11. package/dist/der.d.ts +67 -0
  12. package/dist/der.js +221 -0
  13. package/dist/glob.d.ts +64 -0
  14. package/dist/glob.js +218 -0
  15. package/dist/hex.d.ts +17 -0
  16. package/dist/hex.js +30 -0
  17. package/dist/http.d.ts +46 -0
  18. package/dist/http.js +102 -0
  19. package/dist/json5.d.ts +46 -0
  20. package/dist/json5.js +291 -0
  21. package/dist/media-types.d.ts +28 -0
  22. package/dist/media-types.js +121 -0
  23. package/dist/mod.d.ts +39 -0
  24. package/dist/mod.js +31 -0
  25. package/dist/png.d.ts +124 -0
  26. package/dist/png.js +607 -0
  27. package/dist/semver.d.ts +94 -0
  28. package/dist/semver.js +331 -0
  29. package/dist/toml.d.ts +51 -0
  30. package/dist/toml.js +583 -0
  31. package/dist/ts-literal.d.ts +62 -0
  32. package/dist/ts-literal.js +173 -0
  33. package/dist/xml.d.ts +73 -0
  34. package/dist/xml.js +282 -0
  35. package/dist/yaml.d.ts +44 -0
  36. package/dist/yaml.js +706 -0
  37. package/package.json +118 -4
  38. package/src/archive.ts +831 -0
  39. package/src/base64.ts +51 -0
  40. package/src/cbor.ts +235 -0
  41. package/src/csv.ts +132 -0
  42. package/src/der.ts +224 -0
  43. package/src/glob.ts +210 -0
  44. package/src/hex.ts +28 -0
  45. package/src/http.ts +104 -0
  46. package/src/json5.ts +267 -0
  47. package/src/media-types.ts +127 -0
  48. package/src/mod.ts +102 -0
  49. package/src/png.ts +625 -0
  50. package/src/semver.ts +373 -0
  51. package/src/toml.ts +525 -0
  52. package/src/ts-literal.ts +183 -0
  53. package/src/xml.ts +291 -0
  54. package/src/yaml.ts +616 -0
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Versions: semantic versions by the rules of semver.org 2.0.0 (parsed, printed, ordered and bumped), and the looser dotted versions that
3
+ * programs print (`2.9.8`, `1.4.4`, `26.13.1`), compared part by part (commons 0001-formats FR-015); and npm's ranges, read and
4
+ * satisfied as node-semver reads them (FR-067). Taken from erga's kernel (`semver.ts`) and toolchain (`atLeast`), Stolos's
5
+ * `tools/version.ts` and the machine setup.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { atLeast, compareSemVer, parseSemVer } from "./semver.js";
10
+ * atLeast("2.10.0", "2.9.8"); // true
11
+ * const a = parseSemVer("1.0.0-rc.1"), b = parseSemVer("1.0.0");
12
+ * if (a.kind === "ok" && b.kind === "ok") compareSemVer(a.value, b.value); // negative: a pre-release comes first
13
+ * ```
14
+ *
15
+ * @module
16
+ */
17
+ import { type Result } from "@intellectual-frontiers/core";
18
+ /** A semantic version: major, minor and patch, and an optional pre-release and build, each as its dot-separated text. */
19
+ export type SemVer = {
20
+ readonly major: number;
21
+ readonly minor: number;
22
+ readonly patch: number;
23
+ readonly pre?: string;
24
+ readonly build?: string;
25
+ };
26
+ /** Text read as a semantic version (a leading `v` allowed, as tags carry it), or why it is not one. */
27
+ export declare function parseSemVer(text: string): Result<SemVer, string>;
28
+ /** A version as text: `1.2.3`, `1.2.3-rc.1` or `1.2.3-rc.1+build.5`. */
29
+ export declare function formatSemVer(v: SemVer): string;
30
+ /**
31
+ * Negative where `a` comes before `b`, positive where after, zero where they have the same precedence (semver.org 2.0.0 §11): numbers
32
+ * numerically, a pre-release before its release, pre-release identifiers one by one (numeric ones numerically and before the others), and
33
+ * the build ignored.
34
+ */
35
+ export declare function compareSemVer(a: SemVer, b: SemVer): number;
36
+ /** Which part of a version a change raises. */
37
+ export type Level = "major" | "minor" | "patch";
38
+ /** The next version at a level: the parts after it reset to zero, and the pre-release and build dropped. */
39
+ export declare function bump(v: SemVer, level: Level): SemVer;
40
+ /** The change a surface made, and so the least its version must change by. */
41
+ export type Change = {
42
+ readonly kind: "none";
43
+ } | {
44
+ readonly kind: "fix";
45
+ } | {
46
+ readonly kind: "addition";
47
+ } | {
48
+ readonly kind: "breaking";
49
+ };
50
+ /** Whether moving from `before` to `after` is enough for `change`; before 1.0 a breaking change needs only the minor raised. */
51
+ export declare function bumpSuffices(before: SemVer, after: SemVer, change: Change): boolean;
52
+ /** The numbers of a dotted version: split at `.`, `+`, `_` and `-`, each part's leading digits, and 0 where a part has none. */
53
+ export declare function dottedParts(version: string): readonly number[];
54
+ /** Negative, zero or positive as dotted version `a` is below, equal to or above `b`, part by part; a missing part counts as 0. */
55
+ export declare function compareDotted(a: string, b: string): number;
56
+ /** Whether dotted version `have` is at least `want`. */
57
+ export declare function atLeast(have: string, want: string): boolean;
58
+ /** The first dotted version in a program's output (`bun 1.4.4 (...)` gives `1.4.4`), or undefined. */
59
+ export declare function versionIn(text: string): string | undefined;
60
+ /** How a comparator compares a version with its bound. */
61
+ export type Operator = "<" | "<=" | ">" | ">=" | "=";
62
+ /** A version compared with one bound: `>=1.2.3`, `<2.0.0-0`. */
63
+ export type Comparator = {
64
+ readonly op: Operator;
65
+ readonly version: SemVer;
66
+ };
67
+ /**
68
+ * A range: sets of comparators joined by `||`. A version satisfies it where it satisfies every comparator of one set; an empty set holds
69
+ * every version (`*`), and no set at all holds none.
70
+ */
71
+ export type Range = {
72
+ readonly kind: "range";
73
+ readonly sets: readonly (readonly Comparator[])[];
74
+ };
75
+ /**
76
+ * Text read as an npm range (FR-067), by node-semver's grammar and its desugaring: comparators (`<`, `<=`, `>`, `>=`, `=`) joined by
77
+ * spaces, sets joined by `||`, hyphen ranges (`1.2.3 - 2.3.4`), x-ranges (`*`, `x`, `X` or a missing part), tilde (`~`, `~>`) and caret
78
+ * (`^`) ranges, a space allowed after an operator, a leading `v` and builds ignored. Anything else is an error naming the part.
79
+ */
80
+ export declare function parseRange(text: string): Result<Range, string>;
81
+ /** A range as text: each set's comparators joined by spaces (`=` written as the bare version, an empty set as `*`), the sets by ` || `. */
82
+ export declare function formatRange(range: Range): string;
83
+ /** Whether pre-releases are held to the comparators alone (`includePrerelease`), rather than only where a bound names their release. */
84
+ export type SatisfiesOptions = {
85
+ readonly includePrerelease?: boolean;
86
+ };
87
+ /**
88
+ * Whether a version satisfies a range (FR-067): every comparator of one of its sets holds. A pre-release version satisfies a set only where
89
+ * one of its comparators is a pre-release of the same major, minor and patch (`1.2.3-beta.4` satisfies `^1.2.3-beta.2`, `1.2.4-beta`
90
+ * does not satisfy `^1.2.3`), as node-semver has it, unless `includePrerelease` is given, when the comparators alone decide.
91
+ */
92
+ export declare function satisfies(version: SemVer, range: Range, options?: SatisfiesOptions): boolean;
93
+ /** The highest of the versions that satisfy the range, or undefined where none does. */
94
+ export declare function maxSatisfying(versions: readonly SemVer[], range: Range, options?: SatisfiesOptions): SemVer | undefined;
package/dist/semver.js ADDED
@@ -0,0 +1,331 @@
1
+ // Spec: 0001-formats FR-015
2
+ /**
3
+ * Versions: semantic versions by the rules of semver.org 2.0.0 (parsed, printed, ordered and bumped), and the looser dotted versions that
4
+ * programs print (`2.9.8`, `1.4.4`, `26.13.1`), compared part by part (commons 0001-formats FR-015); and npm's ranges, read and
5
+ * satisfied as node-semver reads them (FR-067). Taken from erga's kernel (`semver.ts`) and toolchain (`atLeast`), Stolos's
6
+ * `tools/version.ts` and the machine setup.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * import { atLeast, compareSemVer, parseSemVer } from "./semver.ts";
11
+ * atLeast("2.10.0", "2.9.8"); // true
12
+ * const a = parseSemVer("1.0.0-rc.1"), b = parseSemVer("1.0.0");
13
+ * if (a.kind === "ok" && b.kind === "ok") compareSemVer(a.value, b.value); // negative: a pre-release comes first
14
+ * ```
15
+ *
16
+ * @module
17
+ */
18
+ import { absurd, err, ok } from "@intellectual-frontiers/core";
19
+ const NUMERIC = /^(0|[1-9][0-9]*)$/;
20
+ const PATTERN = /^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
21
+ /** Text read as a semantic version (a leading `v` allowed, as tags carry it), or why it is not one. */
22
+ export function parseSemVer(text) {
23
+ const m = PATTERN.exec(text.trim());
24
+ if (m === null)
25
+ return err(`${JSON.stringify(text)} is not a semantic version (major.minor.patch[-pre][+build])`);
26
+ const [, major = "", minor = "", patch = "", pre, build] = m;
27
+ const parts = [Number(major), Number(minor), Number(patch)];
28
+ if (!parts.every(Number.isSafeInteger))
29
+ return err(`${JSON.stringify(text)} has a number too large`);
30
+ return ok({
31
+ major: parts[0],
32
+ minor: parts[1],
33
+ patch: parts[2],
34
+ ...(pre === undefined ? {} : { pre }),
35
+ ...(build === undefined ? {} : { build }),
36
+ });
37
+ }
38
+ /** A version as text: `1.2.3`, `1.2.3-rc.1` or `1.2.3-rc.1+build.5`. */
39
+ export function formatSemVer(v) {
40
+ return `${v.major}.${v.minor}.${v.patch}${v.pre === undefined ? "" : `-${v.pre}`}${v.build === undefined ? "" : `+${v.build}`}`;
41
+ }
42
+ function comparePre(a, b) {
43
+ const x = a.split(".");
44
+ const y = b.split(".");
45
+ for (let i = 0; i < Math.min(x.length, y.length); i++) {
46
+ const p = x[i] ?? "";
47
+ const q = y[i] ?? "";
48
+ if (p === q)
49
+ continue;
50
+ const pn = NUMERIC.test(p);
51
+ const qn = NUMERIC.test(q);
52
+ if (pn && qn)
53
+ return Number(p) - Number(q);
54
+ if (pn)
55
+ return -1;
56
+ if (qn)
57
+ return 1;
58
+ return p < q ? -1 : 1;
59
+ }
60
+ return x.length - y.length;
61
+ }
62
+ /**
63
+ * Negative where `a` comes before `b`, positive where after, zero where they have the same precedence (semver.org 2.0.0 §11): numbers
64
+ * numerically, a pre-release before its release, pre-release identifiers one by one (numeric ones numerically and before the others), and
65
+ * the build ignored.
66
+ */
67
+ export function compareSemVer(a, b) {
68
+ const d = a.major - b.major || a.minor - b.minor || a.patch - b.patch;
69
+ if (d !== 0)
70
+ return Math.sign(d);
71
+ if (a.pre === b.pre)
72
+ return 0;
73
+ if (a.pre === undefined)
74
+ return 1;
75
+ if (b.pre === undefined)
76
+ return -1;
77
+ return Math.sign(comparePre(a.pre, b.pre));
78
+ }
79
+ /** The next version at a level: the parts after it reset to zero, and the pre-release and build dropped. */
80
+ export function bump(v, level) {
81
+ switch (level) {
82
+ case "major":
83
+ return { major: v.major + 1, minor: 0, patch: 0 };
84
+ case "minor":
85
+ return { major: v.major, minor: v.minor + 1, patch: 0 };
86
+ case "patch":
87
+ return { major: v.major, minor: v.minor, patch: v.patch + 1 };
88
+ default:
89
+ return absurd(level);
90
+ }
91
+ }
92
+ /** Whether moving from `before` to `after` is enough for `change`; before 1.0 a breaking change needs only the minor raised. */
93
+ export function bumpSuffices(before, after, change) {
94
+ const raised = (key) => after[key] > before[key];
95
+ switch (change.kind) {
96
+ case "none":
97
+ return true;
98
+ case "fix":
99
+ return compareSemVer(after, before) > 0;
100
+ case "addition":
101
+ return raised("minor") || raised("major");
102
+ case "breaking":
103
+ return before.major === 0 ? raised("minor") || raised("major") : raised("major");
104
+ default:
105
+ return absurd(change);
106
+ }
107
+ }
108
+ /** The numbers of a dotted version: split at `.`, `+`, `_` and `-`, each part's leading digits, and 0 where a part has none. */
109
+ export function dottedParts(version) {
110
+ return version
111
+ .trim()
112
+ .replace(/^v/, "")
113
+ .split(/[.+_-]/)
114
+ .map((p) => Number.parseInt(p, 10))
115
+ .map((n) => (Number.isNaN(n) ? 0 : n));
116
+ }
117
+ /** Negative, zero or positive as dotted version `a` is below, equal to or above `b`, part by part; a missing part counts as 0. */
118
+ export function compareDotted(a, b) {
119
+ const x = dottedParts(a);
120
+ const y = dottedParts(b);
121
+ for (let i = 0; i < Math.max(x.length, y.length); i++) {
122
+ const d = (x[i] ?? 0) - (y[i] ?? 0);
123
+ if (d !== 0)
124
+ return Math.sign(d);
125
+ }
126
+ return 0;
127
+ }
128
+ /** Whether dotted version `have` is at least `want`. */
129
+ export function atLeast(have, want) {
130
+ return compareDotted(have, want) >= 0;
131
+ }
132
+ /** The first dotted version in a program's output (`bun 1.4.4 (...)` gives `1.4.4`), or undefined. */
133
+ export function versionIn(text) {
134
+ return /\d+(?:\.\d+)+/.exec(text)?.[0];
135
+ }
136
+ const IDENT = "(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)";
137
+ const PART = "(0|[1-9][0-9]*|[xX*])";
138
+ const PARTIAL = new RegExp(`^v?${PART}(?:\\.${PART}(?:\\.${PART}(?:-(${IDENT}(?:\\.${IDENT})*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?)?)?$`);
139
+ function partial(text) {
140
+ const m = PARTIAL.exec(text);
141
+ if (m === null)
142
+ return err(`${JSON.stringify(text)} is not a version, nor a partial one such as 1.x`);
143
+ const [, a, b, c, pre] = m;
144
+ const parts = [a, b, c].map((p) => (p === undefined || p === "x" || p === "X" || p === "*" ? undefined : Number(p)));
145
+ const [major, minor, patch] = parts;
146
+ const wild = parts.findIndex((p) => p === undefined);
147
+ if (wild >= 0 && parts.slice(wild).some((p) => p !== undefined))
148
+ return err(`${JSON.stringify(text)} has a number after a wildcard`);
149
+ if (!parts.every((p) => p === undefined || Number.isSafeInteger(p)))
150
+ return err(`${JSON.stringify(text)} has a number too large`);
151
+ if (pre !== undefined && patch === undefined)
152
+ return err(`${JSON.stringify(text)} has a pre-release but no patch`);
153
+ return ok({
154
+ ...(major === undefined ? {} : { major }),
155
+ ...(minor === undefined ? {} : { minor }),
156
+ ...(patch === undefined ? {} : { patch }),
157
+ ...(pre === undefined ? {} : { pre }),
158
+ });
159
+ }
160
+ const ver = (major, minor, patch, pre) => ({
161
+ major,
162
+ minor,
163
+ patch,
164
+ ...(pre === undefined ? {} : { pre }),
165
+ });
166
+ const at = (op, version) => ({ op, version });
167
+ /** Below every version: what `<0.0.0-0` says, a set no version satisfies. */
168
+ const NOTHING = [at("<", ver(0, 0, 0, "0"))];
169
+ /** `^`: changes that do not modify the left-most non-zero part (`^1.2.3` is `>=1.2.3 <2.0.0-0`, `^0.2.3` is `>=0.2.3 <0.3.0-0`). */
170
+ function caret(p) {
171
+ const { major: M, minor: m, patch: q, pre } = p;
172
+ if (M === undefined)
173
+ return [];
174
+ if (m === undefined)
175
+ return [at(">=", ver(M, 0, 0)), at("<", ver(M + 1, 0, 0, "0"))];
176
+ if (q === undefined)
177
+ return [at(">=", ver(M, m, 0)), at("<", M === 0 ? ver(0, m + 1, 0, "0") : ver(M + 1, 0, 0, "0"))];
178
+ const upper = M > 0 ? ver(M + 1, 0, 0, "0") : m > 0 ? ver(0, m + 1, 0, "0") : ver(0, 0, q + 1, "0");
179
+ return [at(">=", ver(M, m, q, pre)), at("<", upper)];
180
+ }
181
+ /** `~`: patch changes where a minor is given, minor changes where not (`~1.2.3` is `>=1.2.3 <1.3.0-0`, `~1` is `>=1.0.0 <2.0.0-0`). */
182
+ function tilde(p) {
183
+ const { major: M, minor: m, patch: q, pre } = p;
184
+ if (M === undefined)
185
+ return [];
186
+ if (m === undefined)
187
+ return [at(">=", ver(M, 0, 0)), at("<", ver(M + 1, 0, 0, "0"))];
188
+ return [at(">=", ver(M, m, q ?? 0, q === undefined ? undefined : pre)), at("<", ver(M, m + 1, 0, "0"))];
189
+ }
190
+ /** A comparator or a bare version, either maybe partial (`>1.2` is `>=1.3.0`, `<=1` is `<2.0.0-0`, `1.2` is `>=1.2.0 <1.3.0-0`). */
191
+ function primitive(op, p) {
192
+ const { major: M, minor: m, patch: q, pre } = p;
193
+ if (M === undefined)
194
+ return op === "<" || op === ">" ? NOTHING : [];
195
+ if (m !== undefined && q !== undefined)
196
+ return [at(op, ver(M, m, q, pre))];
197
+ // the next version a wildcard leaves out: 2.0.0 for 1.x, 1.3.0 for 1.2.x
198
+ const next = m === undefined ? ver(M + 1, 0, 0) : ver(M, m + 1, 0);
199
+ const first = ver(M, m ?? 0, 0);
200
+ switch (op) {
201
+ case ">":
202
+ return [at(">=", next)];
203
+ case ">=":
204
+ return [at(">=", first)];
205
+ case "<":
206
+ return [at("<", ver(first.major, first.minor, 0, "0"))];
207
+ case "<=":
208
+ return [at("<", { ...next, pre: "0" })];
209
+ case "=":
210
+ return [at(">=", first), at("<", { ...next, pre: "0" })];
211
+ default:
212
+ return absurd(op);
213
+ }
214
+ }
215
+ /** `A - B`: at least `A`, at most `B` (`1.2 - 2.3.4` is `>=1.2.0 <=2.3.4`, `1.2.3 - 2` is `>=1.2.3 <3.0.0-0`). */
216
+ function hyphen(from, to) {
217
+ const lower = from.major === undefined ? [] : primitive(">=", from);
218
+ const upper = to.major === undefined ? [] : primitive("<=", to);
219
+ return [...lower, ...upper];
220
+ }
221
+ const OPERATOR = /^(<=|>=|<|>|=|~>|~|\^)?(.*)$/;
222
+ function set(text) {
223
+ const trimmed = text.trim();
224
+ const range = /^(\S+)\s+-\s+(\S+)$/.exec(trimmed);
225
+ if (range !== null) {
226
+ const from = partial(range[1] ?? "");
227
+ if (from.kind === "err")
228
+ return from;
229
+ const to = partial(range[2] ?? "");
230
+ if (to.kind === "err")
231
+ return to;
232
+ return ok(hyphen(from.value, to.value));
233
+ }
234
+ const words = trimmed
235
+ .replace(/(<=|>=|<|>|=|~>|~|\^)\s+/g, "$1")
236
+ .split(/\s+/)
237
+ .filter((w) => w !== "");
238
+ const out = [];
239
+ for (const word of words) {
240
+ const m = OPERATOR.exec(word);
241
+ const op = m?.[1];
242
+ const rest = m?.[2] ?? "";
243
+ if (rest === "")
244
+ return err(`${JSON.stringify(word)} has no version after its operator`);
245
+ const p = partial(rest);
246
+ if (p.kind === "err")
247
+ return p;
248
+ switch (op) {
249
+ case "^":
250
+ out.push(...caret(p.value));
251
+ break;
252
+ case "~":
253
+ case "~>":
254
+ out.push(...tilde(p.value));
255
+ break;
256
+ case "<":
257
+ case "<=":
258
+ case ">":
259
+ case ">=":
260
+ case "=":
261
+ out.push(...primitive(op, p.value));
262
+ break;
263
+ case undefined:
264
+ out.push(...primitive("=", p.value));
265
+ break;
266
+ default:
267
+ return err(`${JSON.stringify(word)} has an operator that is not one`);
268
+ }
269
+ }
270
+ return ok(out);
271
+ }
272
+ /**
273
+ * Text read as an npm range (FR-067), by node-semver's grammar and its desugaring: comparators (`<`, `<=`, `>`, `>=`, `=`) joined by
274
+ * spaces, sets joined by `||`, hyphen ranges (`1.2.3 - 2.3.4`), x-ranges (`*`, `x`, `X` or a missing part), tilde (`~`, `~>`) and caret
275
+ * (`^`) ranges, a space allowed after an operator, a leading `v` and builds ignored. Anything else is an error naming the part.
276
+ */
277
+ export function parseRange(text) {
278
+ const sets = [];
279
+ for (const part of text.split("||")) {
280
+ const s = set(part);
281
+ if (s.kind === "err")
282
+ return err(`${JSON.stringify(text)} is not a range: ${s.error}`);
283
+ sets.push(s.value);
284
+ }
285
+ return ok({ kind: "range", sets });
286
+ }
287
+ /** A range as text: each set's comparators joined by spaces (`=` written as the bare version, an empty set as `*`), the sets by ` || `. */
288
+ export function formatRange(range) {
289
+ return range.sets
290
+ .map((s) => (s.length === 0 ? "*" : s.map((c) => `${c.op === "=" ? "" : c.op}${formatSemVer(c.version)}`).join(" ")))
291
+ .join(" || ");
292
+ }
293
+ function holds(c, v) {
294
+ const d = compareSemVer(v, c.version);
295
+ switch (c.op) {
296
+ case "<":
297
+ return d < 0;
298
+ case "<=":
299
+ return d <= 0;
300
+ case ">":
301
+ return d > 0;
302
+ case ">=":
303
+ return d >= 0;
304
+ case "=":
305
+ return d === 0;
306
+ default:
307
+ return absurd(c.op);
308
+ }
309
+ }
310
+ /**
311
+ * Whether a version satisfies a range (FR-067): every comparator of one of its sets holds. A pre-release version satisfies a set only where
312
+ * one of its comparators is a pre-release of the same major, minor and patch (`1.2.3-beta.4` satisfies `^1.2.3-beta.2`, `1.2.4-beta`
313
+ * does not satisfy `^1.2.3`), as node-semver has it, unless `includePrerelease` is given, when the comparators alone decide.
314
+ */
315
+ export function satisfies(version, range, options = {}) {
316
+ return range.sets.some((s) => s.every((c) => holds(c, version)) &&
317
+ (version.pre === undefined ||
318
+ options.includePrerelease === true ||
319
+ s.some((c) => c.version.pre !== undefined &&
320
+ c.version.major === version.major &&
321
+ c.version.minor === version.minor &&
322
+ c.version.patch === version.patch)));
323
+ }
324
+ /** The highest of the versions that satisfy the range, or undefined where none does. */
325
+ export function maxSatisfying(versions, range, options = {}) {
326
+ let best;
327
+ for (const v of versions)
328
+ if (satisfies(v, range, options) && (best === undefined || compareSemVer(v, best) > 0))
329
+ best = v;
330
+ return best;
331
+ }
package/dist/toml.d.ts ADDED
@@ -0,0 +1,51 @@
1
+ /**
2
+ * TOML 1.0.0 (https://toml.io/en/v1.0.0), read and written with no outside package (commons 0001-formats FR-003). The reader
3
+ * takes the whole language (bare, quoted and dotted keys; tables, arrays of tables and inline tables; the four kinds of string; decimal,
4
+ * hexadecimal, octal and binary integers; floats with `inf` and `nan`; the four kinds of date and time) and holds to its rules: no key or
5
+ * table defined twice, an inline table or a static array never extended, a table made by dotted keys never reopened by a header. It
6
+ * gives a typed `TomlTable`, or the line and column where the text stops being TOML. An integer outside JavaScript's safe range is refused
7
+ * rather than rounded. A date or time stays as its text, with its kind. The writer gives TOML the reader reads back as the same table.
8
+ * Replaces `@std/toml` in erga.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * import { parseToml } from "./toml.js";
13
+ * parseToml('[server]\nhost = "127.0.0.1"\nports = [8000, 8001]\n');
14
+ * // { kind: "ok", value: { server: { host: "127.0.0.1", ports: [8000, 8001] } } }
15
+ * ```
16
+ *
17
+ * @module
18
+ */
19
+ import { type Result } from "@intellectual-frontiers/core";
20
+ /** A date, a time, or both, as TOML wrote it (a space between date and time made `T`), with which of the four it is. */
21
+ export type TomlDateTime = {
22
+ readonly kind: "offset-date-time" | "local-date-time" | "local-date" | "local-time";
23
+ readonly text: string;
24
+ };
25
+ /** A TOML value. */
26
+ export type TomlValue = string | number | boolean | TomlDateTime | readonly TomlValue[] | TomlTable;
27
+ /** A TOML table: its keys in the order they were defined. */
28
+ export type TomlTable = {
29
+ readonly [key: string]: TomlValue;
30
+ };
31
+ /** Where a text stops being TOML, and why. Lines and columns count from 1. */
32
+ export type TomlError = {
33
+ readonly kind: "toml";
34
+ readonly line: number;
35
+ readonly column: number;
36
+ readonly message: string;
37
+ };
38
+ /** A TOML error as one line: `3:14: expected a value`. */
39
+ export declare function formatTomlError(e: TomlError): string;
40
+ /** Whether a TOML value is a date or time. */
41
+ export declare function isTomlDateTime(v: TomlValue): v is TomlDateTime;
42
+ /** Whether a TOML value is a table (not an array, not a date or time). */
43
+ export declare function isTomlTable(v: TomlValue): v is TomlTable;
44
+ /** TOML text read as a table, or where and why it is not TOML. */
45
+ export declare function parseToml(text: string): Result<TomlTable, TomlError>;
46
+ /** A key as TOML writes it: bare where it can be, else a basic string. */
47
+ export declare function tomlKey(k: string): string;
48
+ /** A string as a TOML basic string: `"`, `\` and every control character escaped. */
49
+ export declare function tomlString(s: string): string;
50
+ /** A table as TOML text: plain values first, then each table under its header and each array of tables under `[[...]]`, ending in a line break. */
51
+ export declare function toToml(table: TomlTable): string;