@bendyline/molen-pack 0.0.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.
@@ -0,0 +1,135 @@
1
+ import { PackManifest } from "@bendyline/molen-schema";
2
+
3
+ //#region src/build.d.ts
4
+ interface PackFile {
5
+ /** Pack-relative POSIX path. */
6
+ path: string;
7
+ bytes: Uint8Array;
8
+ }
9
+ interface PackOptions {
10
+ id: string;
11
+ version: string;
12
+ title?: string;
13
+ license?: string;
14
+ /** Path of the file carrying the attribution notice. */
15
+ notice?: string;
16
+ /** Asset id to file path. Ids declared by molen/asset@1 sidecars are added automatically. */
17
+ ids?: Record<string, string>;
18
+ /** Role (e.g. `types`, `stylepack`) to the file or files that provide it. */
19
+ provides?: Record<string, string | readonly string[]>;
20
+ /** Group small text files into compressed solid blocks (default true). */
21
+ solid?: boolean;
22
+ }
23
+ interface BuiltPack {
24
+ bytes: Uint8Array;
25
+ manifest: PackManifest;
26
+ }
27
+ declare function mediaTypeOf(path: string): string;
28
+ declare function isTextPath(path: string): boolean;
29
+ declare function sha256(bytes: Uint8Array): Promise<string>;
30
+ /**
31
+ * Describe files as a pack manifest with no blocks: entries, ids, roles and the content hash.
32
+ * The content hash covers paths and contents only, so a built pack and its unbuilt source
33
+ * directory report the same one.
34
+ */
35
+ declare function describePack(files: readonly PackFile[], options: PackOptions): Promise<PackManifest>;
36
+ /** Build a pack: a deterministic zip whose last member is the manifest. */
37
+ declare function createPack(files: readonly PackFile[], options: PackOptions): Promise<BuiltPack>;
38
+ //#endregion
39
+ //#region src/source.d.ts
40
+ /**
41
+ * Byte sources a pack can be read from, and the transport policy for remote ones: tail-first
42
+ * opening, range reads merged when they are close together, bounded concurrency, and retries.
43
+ */
44
+ /** Random access to a pack's bytes. Supply one for storage Molen does not know about. */
45
+ interface RangeReader {
46
+ /** Total size in bytes. */
47
+ readonly size: number;
48
+ read(offset: number, length: number, signal?: AbortSignal): Promise<Uint8Array>;
49
+ }
50
+ interface PackRetryOptions {
51
+ /** Attempts per request, including the first (default 3). */
52
+ attempts?: number;
53
+ /** Delay before the first retry; doubles each time (default 250 ms). */
54
+ baseDelayMs?: number;
55
+ maxDelayMs?: number;
56
+ /** Per-request deadline (default 30 s). */
57
+ timeoutMs?: number;
58
+ }
59
+ /** The server replaced the pack while it was being read (its ETag changed). */
60
+ declare class PackChangedError extends Error {
61
+ constructor(url: string);
62
+ }
63
+ //#endregion
64
+ //#region src/pack.d.ts
65
+ /** Where a pack's bytes come from: a URL, a file the user picked, bytes, or your own reader. */
66
+ type PackInput = string | URL | Blob | ArrayBuffer | Uint8Array | RangeReader;
67
+ interface PackProgress {
68
+ /** The pack's label (URL, file name, ...). */
69
+ label: string;
70
+ /** Bytes read from the source so far. */
71
+ bytes: number;
72
+ /** Reads (network requests, for a URL) so far. */
73
+ requests: number;
74
+ }
75
+ interface OpenPackOptions {
76
+ /** 'auto' (default) picks whole or range reads; 'whole' downloads the file in one request. */
77
+ mode?: "auto" | "whole" | "range";
78
+ /** Expected size in bytes; with `auto`, packs up to `wholeThreshold` are fetched whole. */
79
+ sizeHint?: number;
80
+ /** Default 4 MiB. */
81
+ wholeThreshold?: number;
82
+ fetch?: typeof fetch;
83
+ /** Aborts opening and every later read. */
84
+ signal?: AbortSignal;
85
+ retry?: PackRetryOptions;
86
+ /** Reads in flight at once (default 6). */
87
+ concurrency?: number;
88
+ /** 'crc' (default) checks each zip member; 'sha256' also checks every file's hash. */
89
+ integrity?: "crc" | "sha256";
90
+ /** Fail to open unless the manifest's contentHash matches. */
91
+ expect?: {
92
+ contentHash: string;
93
+ };
94
+ /** Decoded bytes kept for reuse (default 16 MiB). */
95
+ maxCacheBytes?: number;
96
+ onProgress?(progress: PackProgress): void;
97
+ /** Name used in errors and progress (default: the URL, or "bytes"/"blob"/"reader"). */
98
+ label?: string;
99
+ }
100
+ interface ReadOptions {
101
+ signal?: AbortSignal;
102
+ /** Low-priority reads wait behind high-priority ones (default 'high'). */
103
+ priority?: "high" | "low";
104
+ }
105
+ interface Pack {
106
+ readonly manifest: PackManifest;
107
+ readonly label: string;
108
+ has(path: string): boolean;
109
+ /** Every file path, sorted. */
110
+ paths(): string[];
111
+ readBytes(path: string, options?: ReadOptions): Promise<ArrayBuffer>;
112
+ readText(path: string, options?: ReadOptions): Promise<string>;
113
+ readJson<T = unknown>(path: string, options?: ReadOptions): Promise<T>;
114
+ /** Start fetching files now so later reads are served from the cache. */
115
+ prefetch(paths: readonly string[], options?: ReadOptions): Promise<void>;
116
+ /** Abort outstanding reads and drop cached bytes. */
117
+ close(): void;
118
+ }
119
+ declare class PackEntryNotFoundError extends Error {
120
+ readonly pack: string;
121
+ readonly path: string;
122
+ constructor(pack: string, path: string);
123
+ }
124
+ declare class PackIntegrityError extends Error {
125
+ constructor(pack: string, path: string, detail: string);
126
+ }
127
+ /**
128
+ * A pack over loose files, with the same manifest a built pack of those files would have. For
129
+ * tests, development, and content generated at runtime.
130
+ */
131
+ declare function packFromFiles(files: readonly PackFile[], options: PackOptions, label?: string): Promise<Pack>;
132
+ /** Open a pack. Reads only the manifest and zip directory; files are fetched when read. */
133
+ declare function openPack(input: PackInput, options?: OpenPackOptions): Promise<Pack>;
134
+ //#endregion
135
+ export { describePack as _, PackIntegrityError as a, sha256 as b, openPack as c, PackRetryOptions as d, RangeReader as f, createPack as g, PackOptions as h, PackInput as i, packFromFiles as l, PackFile as m, Pack as n, PackProgress as o, BuiltPack as p, PackEntryNotFoundError as r, ReadOptions as s, OpenPackOptions as t, PackChangedError as u, isTextPath as v, mediaTypeOf as y };
package/package.json ADDED
@@ -0,0 +1,60 @@
1
+ {
2
+ "name": "@bendyline/molen-pack",
3
+ "version": "0.0.1",
4
+ "private": false,
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "type": "module",
9
+ "engines": {
10
+ "node": ">=22.13.0"
11
+ },
12
+ "description": "Molen content packs: build, open and read zip packs of models and documents from any source",
13
+ "license": "MIT",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/bendyline/molen.git",
17
+ "directory": "packages/pack"
18
+ },
19
+ "homepage": "https://github.com/bendyline/molen/tree/main/packages/pack",
20
+ "bugs": {
21
+ "url": "https://github.com/bendyline/molen/issues"
22
+ },
23
+ "keywords": [
24
+ "molen",
25
+ "3d",
26
+ "assets",
27
+ "zip",
28
+ "content"
29
+ ],
30
+ "exports": {
31
+ ".": {
32
+ "types": "./dist/index.d.mts",
33
+ "default": "./dist/index.mjs"
34
+ },
35
+ "./node": {
36
+ "types": "./dist/node.d.mts",
37
+ "default": "./dist/node.mjs"
38
+ }
39
+ },
40
+ "files": [
41
+ "dist"
42
+ ],
43
+ "dependencies": {
44
+ "fflate": "0.8.3",
45
+ "@bendyline/molen-schema": "0.0.1"
46
+ },
47
+ "devDependencies": {
48
+ "@biomejs/biome": "^2.5.0",
49
+ "@types/node": "^24",
50
+ "tsdown": "^0.22.2",
51
+ "typescript": "^6.0.3",
52
+ "vitest": "^4.1.8"
53
+ },
54
+ "scripts": {
55
+ "build": "tsdown",
56
+ "typecheck": "tsc -p tsconfig.json",
57
+ "lint": "biome check src",
58
+ "test:unit": "vitest run --passWithNoTests"
59
+ }
60
+ }