@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/dist/png.d.ts ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Pictures with no outside package (commons 0001-formats FR-012): a PNG read into eight-bit RGBA and written back, a picture
3
+ * resized with Pillow's Lanczos filter in its fixed point (on premultiplied alpha for RGBA), laid over another as Pillow's `alpha_composite`
4
+ * lays it, fitted as Pillow's `thumbnail` fits it, gathered into a multi-size icon file of PNG frames and read back from one, and two files
5
+ * compared by their pixels rather than their bytes (two zlib encoders give different bytes for one picture). Also a `#rrggbb` colour read
6
+ * into its channels and its relative luminance as WCAG measures it.
7
+ *
8
+ * The reader takes every PNG that is not interlaced: greyscale at 1, 2, 4, 8 and 16 bits, palette at 1, 2, 4 and 8 bits, and RGB,
9
+ * greyscale with alpha and RGBA at 8 and 16 bits, with `tRNS` transparency for greyscale, RGB and palette, and every filter (None, Sub,
10
+ * Up, Average, Paeth). Sixteen-bit samples keep their high byte. It refuses what is not a PNG it can trust, with a typed `PngError`: a bad
11
+ * signature, a chunk whose CRC-32 is wrong, data cut short, a colour type and bit depth PNG does not define, an interlaced (Adam7) picture,
12
+ * an unknown critical chunk, and a picture of more than `MAX_PIXELS` pixels, refused before anything is allocated or inflated for it; the
13
+ * inflater is stopped as soon as it gives more bytes than the picture needs, so a small hostile file cannot make it allocate more.
14
+ * Writers take a well-formed picture; a malformed one (a size that is not a positive integer, data of the wrong length) is a programming
15
+ * error and throws a `RangeError`.
16
+ *
17
+ * Taken from erga's `lib/ts/png`. What changed: readers return a typed error rather than a sentence, check every chunk's CRC and the
18
+ * picture's size, read the sub-byte depths and the `tRNS` of greyscale and RGB that erga ignored, and refuse an out-of-range palette index;
19
+ * erga's `resize` (each channel alone) is `resizeChannels` and its `resized` (on premultiplied alpha) is `resize`; `hexRgb` returns
20
+ * `undefined` for what is not a colour rather than black, and `luminance` takes channels rather than a hex string; `composite` clips an
21
+ * overlay that starts left of or above its base, and `premultiply` leaves a picture without alpha as it is.
22
+ *
23
+ * @example
24
+ * ```ts
25
+ * import { filled, readPng, writePng } from "./png.js";
26
+ * const png = await writePng(filled(2, 2, [255, 0, 0, 128]));
27
+ * await readPng(png); // { kind: "ok", value: { width: 2, height: 2, channels: 4, data: Uint8Array [255, 0, 0, 128, ...] } }
28
+ * ```
29
+ *
30
+ * @module
31
+ */
32
+ import { type Result } from "@intellectual-frontiers/core";
33
+ /** A raster: its size, its channels (3 for RGB, 4 for RGBA) and its bytes, row by row, eight bits a channel. */
34
+ export type Picture = {
35
+ readonly width: number;
36
+ readonly height: number;
37
+ readonly channels: 3 | 4;
38
+ readonly data: Uint8Array;
39
+ };
40
+ /** A colour's red, green and blue, each 0 to 255. */
41
+ export type Rgb = readonly [number, number, number];
42
+ /** A colour's red, green, blue and alpha, each 0 to 255. */
43
+ export type Rgba = readonly [number, number, number, number];
44
+ /**
45
+ * The most pixels a picture read may have: 2^24 (16,777,216, a 4096 by 4096 square). Its RGBA is then at most 64 MiB, and the inflated
46
+ * data of the largest kind (16-bit RGBA) at most 128 MiB. A file that declares more is refused as `too-large` before anything is read.
47
+ */
48
+ export declare const MAX_PIXELS: number;
49
+ /** Why bytes are not a PNG or icon file this reader takes. */
50
+ export type PngError = {
51
+ readonly kind: "signature";
52
+ readonly format: "png" | "ico";
53
+ } | {
54
+ readonly kind: "crc";
55
+ readonly chunk: string;
56
+ readonly at: number;
57
+ } | {
58
+ readonly kind: "truncated";
59
+ readonly message: string;
60
+ } | {
61
+ readonly kind: "malformed";
62
+ readonly message: string;
63
+ } | {
64
+ readonly kind: "unsupported";
65
+ readonly message: string;
66
+ } | {
67
+ readonly kind: "interlaced";
68
+ } | {
69
+ readonly kind: "too-large";
70
+ readonly width: number;
71
+ readonly height: number;
72
+ readonly limit: number;
73
+ } | {
74
+ readonly kind: "ico-frame";
75
+ readonly index: number;
76
+ readonly error: PngError;
77
+ };
78
+ /** A PNG error as one sentence. */
79
+ export declare function formatPngError(e: PngError): string;
80
+ /** A picture of one colour, RGBA. A size that is not a positive integer throws a `RangeError`. */
81
+ export declare function filled(width: number, height: number, rgba: Rgba): Picture;
82
+ /** The picture without its alpha; a picture without alpha as it is. */
83
+ export declare function rgbOf(p: Picture): Picture;
84
+ /** The picture with alpha, opaque where it had none; a picture with alpha as it is. */
85
+ export declare function rgbaOf(p: Picture): Picture;
86
+ /** A PNG read into eight-bit RGBA, its filters undone and its palette and transparency applied; or why it cannot be. */
87
+ export declare function readPng(bytes: Uint8Array): Promise<Result<Picture, PngError>>;
88
+ /** A picture written as an eight-bit RGB or RGBA PNG, each row unfiltered, its zlib stream the platform's `CompressionStream`. */
89
+ export declare function writePng(p: Picture): Promise<Uint8Array>;
90
+ /** The picture with each colour channel multiplied by its alpha, rounded as Pillow rounds; a picture without alpha as it is. */
91
+ export declare function premultiply(p: Picture): Picture;
92
+ /** The picture with each colour channel divided by its alpha again, as Pillow divides; a picture without alpha as it is. */
93
+ export declare function unpremultiply(p: Picture): Picture;
94
+ /**
95
+ * A picture resized with Pillow's Lanczos filter in its fixed point, each channel filtered on its own (alpha too, and the colour channels
96
+ * without regard to it). A size that is not a positive integer throws a `RangeError`.
97
+ */
98
+ export declare function resizeChannels(p: Picture, width: number, height: number): Picture;
99
+ /** A picture resized as Pillow resizes it with its Lanczos filter: an RGBA picture on premultiplied alpha. The same size gives it back. */
100
+ export declare function resize(p: Picture, width: number, height: number): Picture;
101
+ /**
102
+ * `over` laid on `base` with its top left corner at `(left, top)`, as Pillow's `alpha_composite` lays it; what falls outside `base` is
103
+ * cut off. The result has alpha; a picture without alpha is taken as opaque.
104
+ */
105
+ export declare function composite(base: Picture, over: Picture, left: number, top: number): Picture;
106
+ /** `art` laid at `(left, top)` on an opaque canvas of `colour`, the result without alpha. */
107
+ export declare function flatOn(colour: Rgb, width: number, height: number, art: Picture, left: number, top: number): Picture;
108
+ /** The size Pillow's `thumbnail` gives a picture fitted in `width` by `height`, its aspect kept; `undefined` where it already fits. */
109
+ export declare function thumbnailSize(p: Picture, width: number, height: number): readonly [number, number] | undefined;
110
+ /**
111
+ * A multi-size icon file of PNG frames, as Pillow writes one: one frame for each size asked that is at most the picture's width, height
112
+ * and 256, smallest first, each the picture fitted in that square (`thumbnailSize`) and resized (`resize`).
113
+ */
114
+ export declare function writeIco(p: Picture, sizes: readonly number[]): Promise<Uint8Array>;
115
+ /** Every frame of an icon file whose frames are PNGs, in the order of its directory; or why it cannot be read. */
116
+ export declare function readIco(bytes: Uint8Array): Promise<Result<readonly Picture[], PngError>>;
117
+ /** Whether two pictures have the same size and the same RGBA pixels (a picture without alpha taken as opaque). */
118
+ export declare function samePixels(a: Picture, b: Picture): boolean;
119
+ /** Whether two PNG files, or two icon files, hold the same pictures pixel for pixel, whatever their zlib streams; false where either cannot be read. */
120
+ export declare function samePicture(a: Uint8Array, b: Uint8Array): Promise<boolean>;
121
+ /** A `#rrggbb` or `#rgb` colour (the `#` optional, any case) as its channels; `undefined` for what is not one. */
122
+ export declare function hexRgb(hex: string): Rgb | undefined;
123
+ /** A colour's relative luminance as WCAG 2 measures it, from 0 (black) to 1 (white). */
124
+ export declare function luminance(rgb: Rgb): number;