@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
package/src/semver.ts ADDED
@@ -0,0 +1,373 @@
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, type Result } from "@intellectual-frontiers/core";
19
+
20
+ /** A semantic version: major, minor and patch, and an optional pre-release and build, each as its dot-separated text. */
21
+ export type SemVer = {
22
+ readonly major: number;
23
+ readonly minor: number;
24
+ readonly patch: number;
25
+ readonly pre?: string;
26
+ readonly build?: string;
27
+ };
28
+
29
+ const NUMERIC = /^(0|[1-9][0-9]*)$/;
30
+ const PATTERN =
31
+ /^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-]+)*))?$/;
32
+
33
+ /** Text read as a semantic version (a leading `v` allowed, as tags carry it), or why it is not one. */
34
+ export function parseSemVer(text: string): Result<SemVer, string> {
35
+ const m = PATTERN.exec(text.trim());
36
+ if (m === null) return err(`${JSON.stringify(text)} is not a semantic version (major.minor.patch[-pre][+build])`);
37
+ const [, major = "", minor = "", patch = "", pre, build] = m;
38
+ const parts = [Number(major), Number(minor), Number(patch)] as const;
39
+ if (!parts.every(Number.isSafeInteger)) return err(`${JSON.stringify(text)} has a number too large`);
40
+ return ok({
41
+ major: parts[0],
42
+ minor: parts[1],
43
+ patch: parts[2],
44
+ ...(pre === undefined ? {} : { pre }),
45
+ ...(build === undefined ? {} : { build }),
46
+ });
47
+ }
48
+
49
+ /** A version as text: `1.2.3`, `1.2.3-rc.1` or `1.2.3-rc.1+build.5`. */
50
+ export function formatSemVer(v: SemVer): string {
51
+ return `${v.major}.${v.minor}.${v.patch}${v.pre === undefined ? "" : `-${v.pre}`}${v.build === undefined ? "" : `+${v.build}`}`;
52
+ }
53
+
54
+ function comparePre(a: string, b: string): number {
55
+ const x = a.split(".");
56
+ const y = b.split(".");
57
+ for (let i = 0; i < Math.min(x.length, y.length); i++) {
58
+ const p = x[i] ?? "";
59
+ const q = y[i] ?? "";
60
+ if (p === q) continue;
61
+ const pn = NUMERIC.test(p);
62
+ const qn = NUMERIC.test(q);
63
+ if (pn && qn) return Number(p) - Number(q);
64
+ if (pn) return -1;
65
+ if (qn) return 1;
66
+ return p < q ? -1 : 1;
67
+ }
68
+ return x.length - y.length;
69
+ }
70
+
71
+ /**
72
+ * Negative where `a` comes before `b`, positive where after, zero where they have the same precedence (semver.org 2.0.0 §11): numbers
73
+ * numerically, a pre-release before its release, pre-release identifiers one by one (numeric ones numerically and before the others), and
74
+ * the build ignored.
75
+ */
76
+ export function compareSemVer(a: SemVer, b: SemVer): number {
77
+ const d = a.major - b.major || a.minor - b.minor || a.patch - b.patch;
78
+ if (d !== 0) return Math.sign(d);
79
+ if (a.pre === b.pre) return 0;
80
+ if (a.pre === undefined) return 1;
81
+ if (b.pre === undefined) return -1;
82
+ return Math.sign(comparePre(a.pre, b.pre));
83
+ }
84
+
85
+ /** Which part of a version a change raises. */
86
+ export type Level = "major" | "minor" | "patch";
87
+
88
+ /** The next version at a level: the parts after it reset to zero, and the pre-release and build dropped. */
89
+ export function bump(v: SemVer, level: Level): SemVer {
90
+ switch (level) {
91
+ case "major":
92
+ return { major: v.major + 1, minor: 0, patch: 0 };
93
+ case "minor":
94
+ return { major: v.major, minor: v.minor + 1, patch: 0 };
95
+ case "patch":
96
+ return { major: v.major, minor: v.minor, patch: v.patch + 1 };
97
+ default:
98
+ return absurd(level);
99
+ }
100
+ }
101
+
102
+ /** The change a surface made, and so the least its version must change by. */
103
+ export type Change = { readonly kind: "none" } | { readonly kind: "fix" } | { readonly kind: "addition" } | { readonly kind: "breaking" };
104
+
105
+ /** Whether moving from `before` to `after` is enough for `change`; before 1.0 a breaking change needs only the minor raised. */
106
+ export function bumpSuffices(before: SemVer, after: SemVer, change: Change): boolean {
107
+ const raised = (key: Level): boolean => after[key] > before[key];
108
+ switch (change.kind) {
109
+ case "none":
110
+ return true;
111
+ case "fix":
112
+ return compareSemVer(after, before) > 0;
113
+ case "addition":
114
+ return raised("minor") || raised("major");
115
+ case "breaking":
116
+ return before.major === 0 ? raised("minor") || raised("major") : raised("major");
117
+ default:
118
+ return absurd(change);
119
+ }
120
+ }
121
+
122
+ /** The numbers of a dotted version: split at `.`, `+`, `_` and `-`, each part's leading digits, and 0 where a part has none. */
123
+ export function dottedParts(version: string): readonly number[] {
124
+ return version
125
+ .trim()
126
+ .replace(/^v/, "")
127
+ .split(/[.+_-]/)
128
+ .map((p) => Number.parseInt(p, 10))
129
+ .map((n) => (Number.isNaN(n) ? 0 : n));
130
+ }
131
+
132
+ /** Negative, zero or positive as dotted version `a` is below, equal to or above `b`, part by part; a missing part counts as 0. */
133
+ export function compareDotted(a: string, b: string): number {
134
+ const x = dottedParts(a);
135
+ const y = dottedParts(b);
136
+ for (let i = 0; i < Math.max(x.length, y.length); i++) {
137
+ const d = (x[i] ?? 0) - (y[i] ?? 0);
138
+ if (d !== 0) return Math.sign(d);
139
+ }
140
+ return 0;
141
+ }
142
+
143
+ /** Whether dotted version `have` is at least `want`. */
144
+ export function atLeast(have: string, want: string): boolean {
145
+ return compareDotted(have, want) >= 0;
146
+ }
147
+
148
+ /** The first dotted version in a program's output (`bun 1.4.4 (...)` gives `1.4.4`), or undefined. */
149
+ export function versionIn(text: string): string | undefined {
150
+ return /\d+(?:\.\d+)+/.exec(text)?.[0];
151
+ }
152
+
153
+ // ---------------------------------------------------------------------------------------------------------------------------------
154
+ // Ranges (FR-067), as npm's node-semver reads them
155
+ // ---------------------------------------------------------------------------------------------------------------------------------
156
+
157
+ /** How a comparator compares a version with its bound. */
158
+ export type Operator = "<" | "<=" | ">" | ">=" | "=";
159
+
160
+ /** A version compared with one bound: `>=1.2.3`, `<2.0.0-0`. */
161
+ export type Comparator = { readonly op: Operator; readonly version: SemVer };
162
+
163
+ /**
164
+ * A range: sets of comparators joined by `||`. A version satisfies it where it satisfies every comparator of one set; an empty set holds
165
+ * every version (`*`), and no set at all holds none.
166
+ */
167
+ export type Range = { readonly kind: "range"; readonly sets: readonly (readonly Comparator[])[] };
168
+
169
+ const IDENT = "(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)";
170
+ const PART = "(0|[1-9][0-9]*|[xX*])";
171
+ const PARTIAL = new RegExp(
172
+ `^v?${PART}(?:\\.${PART}(?:\\.${PART}(?:-(${IDENT}(?:\\.${IDENT})*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?)?)?$`,
173
+ );
174
+
175
+ /** A version some of whose parts may be left out or wild (`1`, `1.x`, `1.2.*`); a missing part is `undefined`. */
176
+ type Partial = { readonly major?: number; readonly minor?: number; readonly patch?: number; readonly pre?: string };
177
+
178
+ function partial(text: string): Result<Partial, string> {
179
+ const m = PARTIAL.exec(text);
180
+ if (m === null) return err(`${JSON.stringify(text)} is not a version, nor a partial one such as 1.x`);
181
+ const [, a, b, c, pre] = m;
182
+ const parts = [a, b, c].map((p) => (p === undefined || p === "x" || p === "X" || p === "*" ? undefined : Number(p)));
183
+ const [major, minor, patch] = parts;
184
+ const wild = parts.findIndex((p) => p === undefined);
185
+ if (wild >= 0 && parts.slice(wild).some((p) => p !== undefined)) return err(`${JSON.stringify(text)} has a number after a wildcard`);
186
+ if (!parts.every((p) => p === undefined || Number.isSafeInteger(p))) return err(`${JSON.stringify(text)} has a number too large`);
187
+ if (pre !== undefined && patch === undefined) return err(`${JSON.stringify(text)} has a pre-release but no patch`);
188
+ return ok({
189
+ ...(major === undefined ? {} : { major }),
190
+ ...(minor === undefined ? {} : { minor }),
191
+ ...(patch === undefined ? {} : { patch }),
192
+ ...(pre === undefined ? {} : { pre }),
193
+ });
194
+ }
195
+
196
+ const ver = (major: number, minor: number, patch: number, pre?: string): SemVer => ({
197
+ major,
198
+ minor,
199
+ patch,
200
+ ...(pre === undefined ? {} : { pre }),
201
+ });
202
+ const at = (op: Operator, version: SemVer): Comparator => ({ op, version });
203
+ /** Below every version: what `<0.0.0-0` says, a set no version satisfies. */
204
+ const NOTHING: readonly Comparator[] = [at("<", ver(0, 0, 0, "0"))];
205
+
206
+ /** `^`: 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`). */
207
+ function caret(p: Partial): readonly Comparator[] {
208
+ const { major: M, minor: m, patch: q, pre } = p;
209
+ if (M === undefined) return [];
210
+ if (m === undefined) return [at(">=", ver(M, 0, 0)), at("<", ver(M + 1, 0, 0, "0"))];
211
+ if (q === undefined) return [at(">=", ver(M, m, 0)), at("<", M === 0 ? ver(0, m + 1, 0, "0") : ver(M + 1, 0, 0, "0"))];
212
+ const upper = M > 0 ? ver(M + 1, 0, 0, "0") : m > 0 ? ver(0, m + 1, 0, "0") : ver(0, 0, q + 1, "0");
213
+ return [at(">=", ver(M, m, q, pre)), at("<", upper)];
214
+ }
215
+
216
+ /** `~`: 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`). */
217
+ function tilde(p: Partial): readonly Comparator[] {
218
+ const { major: M, minor: m, patch: q, pre } = p;
219
+ if (M === undefined) return [];
220
+ if (m === undefined) return [at(">=", ver(M, 0, 0)), at("<", ver(M + 1, 0, 0, "0"))];
221
+ return [at(">=", ver(M, m, q ?? 0, q === undefined ? undefined : pre)), at("<", ver(M, m + 1, 0, "0"))];
222
+ }
223
+
224
+ /** 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`). */
225
+ function primitive(op: Operator, p: Partial): readonly Comparator[] {
226
+ const { major: M, minor: m, patch: q, pre } = p;
227
+ if (M === undefined) return op === "<" || op === ">" ? NOTHING : [];
228
+ if (m !== undefined && q !== undefined) return [at(op, ver(M, m, q, pre))];
229
+ // the next version a wildcard leaves out: 2.0.0 for 1.x, 1.3.0 for 1.2.x
230
+ const next = m === undefined ? ver(M + 1, 0, 0) : ver(M, m + 1, 0);
231
+ const first = ver(M, m ?? 0, 0);
232
+ switch (op) {
233
+ case ">":
234
+ return [at(">=", next)];
235
+ case ">=":
236
+ return [at(">=", first)];
237
+ case "<":
238
+ return [at("<", ver(first.major, first.minor, 0, "0"))];
239
+ case "<=":
240
+ return [at("<", { ...next, pre: "0" })];
241
+ case "=":
242
+ return [at(">=", first), at("<", { ...next, pre: "0" })];
243
+ default:
244
+ return absurd(op);
245
+ }
246
+ }
247
+
248
+ /** `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`). */
249
+ function hyphen(from: Partial, to: Partial): readonly Comparator[] {
250
+ const lower = from.major === undefined ? [] : primitive(">=", from);
251
+ const upper = to.major === undefined ? [] : primitive("<=", to);
252
+ return [...lower, ...upper];
253
+ }
254
+
255
+ const OPERATOR = /^(<=|>=|<|>|=|~>|~|\^)?(.*)$/;
256
+
257
+ function set(text: string): Result<readonly Comparator[], string> {
258
+ const trimmed = text.trim();
259
+ const range = /^(\S+)\s+-\s+(\S+)$/.exec(trimmed);
260
+ if (range !== null) {
261
+ const from = partial(range[1] ?? "");
262
+ if (from.kind === "err") return from;
263
+ const to = partial(range[2] ?? "");
264
+ if (to.kind === "err") return to;
265
+ return ok(hyphen(from.value, to.value));
266
+ }
267
+ const words = trimmed
268
+ .replace(/(<=|>=|<|>|=|~>|~|\^)\s+/g, "$1")
269
+ .split(/\s+/)
270
+ .filter((w) => w !== "");
271
+ const out: Comparator[] = [];
272
+ for (const word of words) {
273
+ const m = OPERATOR.exec(word);
274
+ const op = m?.[1];
275
+ const rest = m?.[2] ?? "";
276
+ if (rest === "") return err(`${JSON.stringify(word)} has no version after its operator`);
277
+ const p = partial(rest);
278
+ if (p.kind === "err") return p;
279
+ switch (op) {
280
+ case "^":
281
+ out.push(...caret(p.value));
282
+ break;
283
+ case "~":
284
+ case "~>":
285
+ out.push(...tilde(p.value));
286
+ break;
287
+ case "<":
288
+ case "<=":
289
+ case ">":
290
+ case ">=":
291
+ case "=":
292
+ out.push(...primitive(op, p.value));
293
+ break;
294
+ case undefined:
295
+ out.push(...primitive("=", p.value));
296
+ break;
297
+ default:
298
+ return err(`${JSON.stringify(word)} has an operator that is not one`);
299
+ }
300
+ }
301
+ return ok(out);
302
+ }
303
+
304
+ /**
305
+ * Text read as an npm range (FR-067), by node-semver's grammar and its desugaring: comparators (`<`, `<=`, `>`, `>=`, `=`) joined by
306
+ * spaces, sets joined by `||`, hyphen ranges (`1.2.3 - 2.3.4`), x-ranges (`*`, `x`, `X` or a missing part), tilde (`~`, `~>`) and caret
307
+ * (`^`) ranges, a space allowed after an operator, a leading `v` and builds ignored. Anything else is an error naming the part.
308
+ */
309
+ export function parseRange(text: string): Result<Range, string> {
310
+ const sets: (readonly Comparator[])[] = [];
311
+ for (const part of text.split("||")) {
312
+ const s = set(part);
313
+ if (s.kind === "err") return err(`${JSON.stringify(text)} is not a range: ${s.error}`);
314
+ sets.push(s.value);
315
+ }
316
+ return ok({ kind: "range", sets });
317
+ }
318
+
319
+ /** A range as text: each set's comparators joined by spaces (`=` written as the bare version, an empty set as `*`), the sets by ` || `. */
320
+ export function formatRange(range: Range): string {
321
+ return range.sets
322
+ .map((s) => (s.length === 0 ? "*" : s.map((c) => `${c.op === "=" ? "" : c.op}${formatSemVer(c.version)}`).join(" ")))
323
+ .join(" || ");
324
+ }
325
+
326
+ function holds(c: Comparator, v: SemVer): boolean {
327
+ const d = compareSemVer(v, c.version);
328
+ switch (c.op) {
329
+ case "<":
330
+ return d < 0;
331
+ case "<=":
332
+ return d <= 0;
333
+ case ">":
334
+ return d > 0;
335
+ case ">=":
336
+ return d >= 0;
337
+ case "=":
338
+ return d === 0;
339
+ default:
340
+ return absurd(c.op);
341
+ }
342
+ }
343
+
344
+ /** Whether pre-releases are held to the comparators alone (`includePrerelease`), rather than only where a bound names their release. */
345
+ export type SatisfiesOptions = { readonly includePrerelease?: boolean };
346
+
347
+ /**
348
+ * 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
349
+ * 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`
350
+ * does not satisfy `^1.2.3`), as node-semver has it, unless `includePrerelease` is given, when the comparators alone decide.
351
+ */
352
+ export function satisfies(version: SemVer, range: Range, options: SatisfiesOptions = {}): boolean {
353
+ return range.sets.some(
354
+ (s) =>
355
+ s.every((c) => holds(c, version)) &&
356
+ (version.pre === undefined ||
357
+ options.includePrerelease === true ||
358
+ s.some(
359
+ (c) =>
360
+ c.version.pre !== undefined &&
361
+ c.version.major === version.major &&
362
+ c.version.minor === version.minor &&
363
+ c.version.patch === version.patch,
364
+ )),
365
+ );
366
+ }
367
+
368
+ /** The highest of the versions that satisfy the range, or undefined where none does. */
369
+ export function maxSatisfying(versions: readonly SemVer[], range: Range, options: SatisfiesOptions = {}): SemVer | undefined {
370
+ let best: SemVer | undefined;
371
+ for (const v of versions) if (satisfies(v, range, options) && (best === undefined || compareSemVer(v, best) > 0)) best = v;
372
+ return best;
373
+ }