@intellectual-frontiers/formats 0.0.0-stage → 0.1.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Intellectual Frontiers
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,9 @@
1
- # Temporary Holding Version
1
+ # @intellectual-frontiers/formats
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Formats: JSON5, YAML, TOML, XML, CSV, base64, hexadecimal, ASN.1 DER, CBOR, archives, PNG, TypeScript literals, globs, semantic versions, media types and HTTP headers, read and written in pure code with one dependency, core.
4
+
5
+ ```sh
6
+ bun add @intellectual-frontiers/formats # or: npm install @intellectual-frontiers/formats
7
+ ```
8
+
9
+ Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/formats
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Archives in memory, with no outside package (commons 0001-formats FR-010). Writing: a POSIX ustar archive, a gzip stream of
3
+ * stored deflate blocks and a zip of stored entries (`zip`), each entry with a fixed time and mode and in the byte order of its path, so the
4
+ * bytes depend on the files alone (taken from erga's `lib/ts/archive`); and, where size matters more than the same bytes on every runtime,
5
+ * a zip of deflated entries (`zipDeflated`, through the web standard `CompressionStream`), the same bytes for the same files on one runtime
6
+ * and the same files unzipped on every runtime. Reading: a tar (ustar, pax and GNU long names), a gzip and a zip whose
7
+ * entries are stored or deflated (through the web standard `DecompressionStream`), each checked (header checksums, CRC-32) and every path
8
+ * refused that would leave the folder it is unpacked into. This is what lets Stolos drop `fflate` and unpack a verified copy of its engine.
9
+ * A tar, gzipped or not, is also read as a stream (`untarStream`, `readTarStream`), an entry at a time with each entry's bytes a stream of
10
+ * their own, with the same checks, so that an archive larger than memory can be read (FR-059).
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { tar, untar, zip, unzip } from "./archive.js";
15
+ * const files = new Map([["a/b.txt", new TextEncoder().encode("hello")]]);
16
+ * const z = zip(files);
17
+ * const back = await unzip(z); // { kind: "ok", value: Map { "a/b.txt" => Uint8Array [104, 101, 108, 108, 111] } }
18
+ * ```
19
+ *
20
+ * @module
21
+ */
22
+ import { type Result } from "@intellectual-frontiers/core";
23
+ /** The files of an archive, by their path inside it. */
24
+ export type Files = ReadonlyMap<string, Uint8Array>;
25
+ /** Why an archive could not be read or written. */
26
+ export type ArchiveError = {
27
+ readonly kind: "damaged";
28
+ readonly message: string;
29
+ } | {
30
+ readonly kind: "unsupported";
31
+ readonly message: string;
32
+ } | {
33
+ readonly kind: "unsafe-path";
34
+ readonly path: string;
35
+ } | {
36
+ readonly kind: "too-long";
37
+ readonly path: string;
38
+ };
39
+ /** An archive error as one sentence. */
40
+ export declare function formatArchiveError(e: ArchiveError): string;
41
+ /** The CRC-32 (ISO 3309) that gzip and zip both carry. */
42
+ export declare function crc32(bytes: Uint8Array): number;
43
+ /**
44
+ * Whether a path inside an archive stays inside the folder it is unpacked into: relative, with `/` between its parts, no part `..`, no
45
+ * empty part but a trailing one, no backslash, no drive letter and no NUL.
46
+ */
47
+ export declare function isSafePath(path: string): boolean;
48
+ /** The paths of the files in the byte order of their UTF-8, the order every writer here uses. */
49
+ export declare function sortedPaths(paths: Iterable<string>): readonly string[];
50
+ /** Byte arrays joined end to end. */
51
+ export declare function concat(parts: readonly Uint8Array[]): Uint8Array;
52
+ /** A path too long for the 100 bytes of a ustar name, split into its prefix (up to 155 bytes) and name; undefined where it cannot be. */
53
+ export declare function splitName(path: string): readonly [string, string] | undefined;
54
+ /** One ustar header block of a file (mode 0644) or a folder (0755), owned by user 0, dated 0; undefined where the path does not fit. */
55
+ export declare function tarHeader(path: string, size: number, dir: boolean): Uint8Array | undefined;
56
+ /** A ustar archive of the files, each folder they lie in first given its own entry; or the path that does not fit or is not safe. */
57
+ export declare function tar(files: Files): Result<Uint8Array, ArchiveError>;
58
+ /** A gzip stream (RFC 1952) of the bytes in stored deflate blocks (RFC 1951 §3.2.4), with no name and no time: the same bytes every time. */
59
+ export declare function gzip(data: Uint8Array): Uint8Array;
60
+ /** A date as a zip writes it (MS-DOS): `(year - 1980) << 9 | month << 5 | day`. */
61
+ export declare function dosDate(year: number, month: number, day: number): number;
62
+ /** The zip's fixed date: 1980-01-01, the first a zip can hold. */
63
+ export declare const ZIP_EPOCH: number;
64
+ /** A zip (APPNOTE 6.3) of the files, each stored, dated `date` (1980-01-01 unless another is given) at midnight and readable by everyone. */
65
+ export declare function zip(files: Files, date?: number): Uint8Array;
66
+ /**
67
+ * A zip (APPNOTE 6.3) of the files as `zip` lays them out, but each entry deflated (method 8) through the web standard
68
+ * `CompressionStream("deflate-raw")`, or stored where deflating would not make it smaller (an empty or incompressible file). The bytes
69
+ * depend on the files alone on one runtime; another runtime's deflater may choose other (equally valid) bytes, so only what they unzip to
70
+ * is the same everywhere.
71
+ */
72
+ export declare function zipDeflated(files: Files, date?: number): Promise<Uint8Array>;
73
+ /** The raw deflate stream (RFC 1951) a web `CompressionStream` gives for the bytes. */
74
+ export declare function deflateRaw(data: Uint8Array): Promise<Uint8Array>;
75
+ /** The bytes of a gzip stream, stored or deflated, its CRC checked by the decompressor. */
76
+ export declare function gunzip(data: Uint8Array): Promise<Result<Uint8Array, ArchiveError>>;
77
+ /** One entry of a tar archive. A folder's path has no trailing `/`; a link's target is in `linkName`. */
78
+ export type TarEntry = {
79
+ readonly path: string;
80
+ readonly kind: "file" | "directory" | "symlink" | "hardlink";
81
+ readonly mode: number;
82
+ readonly data: Uint8Array;
83
+ readonly linkName: string;
84
+ };
85
+ /** The header of one entry of a tar archive: its path (a folder's with no trailing `/`), kind, mode, size of body, time and link target. */
86
+ export type TarHeader = {
87
+ readonly path: string;
88
+ readonly kind: TarEntry["kind"];
89
+ readonly mode: number;
90
+ readonly size: number;
91
+ /** Seconds since 1970, as the header (or a pax `mtime`) gives them. */
92
+ readonly mtime: number;
93
+ readonly linkName: string;
94
+ };
95
+ /** The entries of a tar archive (ustar, with pax extended headers and GNU long names), each header's checksum checked and each path checked safe. */
96
+ export declare function untar(data: Uint8Array): Result<readonly TarEntry[], ArchiveError>;
97
+ /** An archive error raised as an `Error`, which is how a stream reports one: the error itself is in `error`. */
98
+ export declare class ArchiveFailure extends Error {
99
+ /** Why the archive could not be read. */
100
+ readonly error: ArchiveError;
101
+ /** An `Error` for the archive error, its message the error's sentence. */
102
+ constructor(error: ArchiveError);
103
+ }
104
+ /**
105
+ * One entry of a tar archive read as a stream: its header and its body as a stream (empty but for a file). The body MUST be read to its
106
+ * end or cancelled before the next entry is given, as with `@std/tar`'s `UntarStream`.
107
+ */
108
+ export type TarStreamEntry = TarHeader & {
109
+ readonly readable: ReadableStream<Uint8Array>;
110
+ };
111
+ /**
112
+ * The entries of a tar archive given as a stream of bytes, gzipped or not (told by its first two bytes), one at a time as they are asked
113
+ * for, so that an archive larger than memory is read with one chunk held (commons 0001-formats FR-011). Every header is checked
114
+ * as `untar` checks it (checksum, pax and GNU long names, a safe path); a failure errors the stream with an `ArchiveFailure`. Each entry's
115
+ * `readable` MUST be read to its end or cancelled before the next entry is given; cancelling the stream of entries cancels the bytes.
116
+ */
117
+ export declare function readTarStream(stream: ReadableStream<Uint8Array>): ReadableStream<TarStreamEntry>;
118
+ /**
119
+ * A stream from a tar archive's bytes, gzipped or not, to its entries, to put in a `pipeThrough` as `@std/tar`'s `UntarStream` is: see
120
+ * `readTarStream` for what it checks and how each entry's body is read (commons 0001-formats FR-011).
121
+ *
122
+ * @example
123
+ * ```ts
124
+ * for await (const entry of file.readable.pipeThrough(untarStream())) {
125
+ * if (entry.path === "bin/tool") await save(entry.readable);
126
+ * else await entry.readable.cancel();
127
+ * }
128
+ * ```
129
+ */
130
+ export declare function untarStream(): ReadableWritablePair<TarStreamEntry, Uint8Array>;
131
+ /** The files of a list of tar entries, by path: folders and links left out. */
132
+ export declare function filesOf(entries: readonly TarEntry[]): Files;
133
+ /** One entry of a zip's central directory. */
134
+ export type ZipEntry = {
135
+ readonly name: string;
136
+ readonly method: number;
137
+ readonly crc: number;
138
+ readonly compressed: number;
139
+ readonly size: number;
140
+ readonly offset: number;
141
+ };
142
+ /** The entries of a zip, from its central directory; or why they cannot be read (a ZIP64 archive among the reasons). */
143
+ export declare function zipEntries(data: Uint8Array): Result<readonly ZipEntry[], ArchiveError>;
144
+ /** The bytes of one entry of a zip, stored (method 0) or deflated (method 8), its size and CRC-32 checked. */
145
+ export declare function zipRead(data: Uint8Array, e: ZipEntry): Promise<Result<Uint8Array, ArchiveError>>;
146
+ /** Every file of a zip by its path, folders left out, each read and checked, and every path checked safe. */
147
+ export declare function unzip(data: Uint8Array): Promise<Result<Files, ArchiveError>>;