@loaders.gl/archives 0.0.0-stage → 5.0.0-alpha.14

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 (168) hide show
  1. package/LICENSE +52 -0
  2. package/README.md +4 -2
  3. package/dist/dist.dev.js +5101 -0
  4. package/dist/dist.min.js +9 -0
  5. package/dist/index.cjs +2982 -0
  6. package/dist/index.cjs.map +6 -0
  7. package/dist/index.d.ts +11 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +11 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/tar/index.cjs +576 -0
  12. package/dist/tar/index.cjs.map +6 -0
  13. package/dist/tar/index.d.ts +8 -0
  14. package/dist/tar/index.d.ts.map +1 -0
  15. package/dist/tar/index.js +9 -0
  16. package/dist/tar/index.js.map +1 -0
  17. package/dist/tar/lib/header.d.ts +9 -0
  18. package/dist/tar/lib/header.d.ts.map +1 -0
  19. package/dist/tar/lib/header.js +76 -0
  20. package/dist/tar/lib/header.js.map +1 -0
  21. package/dist/tar/lib/tar.d.ts +29 -0
  22. package/dist/tar/lib/tar.d.ts.map +1 -0
  23. package/dist/tar/lib/tar.js +136 -0
  24. package/dist/tar/lib/tar.js.map +1 -0
  25. package/dist/tar/lib/types.d.ts +48 -0
  26. package/dist/tar/lib/types.d.ts.map +1 -0
  27. package/dist/tar/lib/types.js +5 -0
  28. package/dist/tar/lib/types.js.map +1 -0
  29. package/dist/tar/lib/utils.d.ts +23 -0
  30. package/dist/tar/lib/utils.d.ts.map +1 -0
  31. package/dist/tar/lib/utils.js +52 -0
  32. package/dist/tar/lib/utils.js.map +1 -0
  33. package/dist/tar/tar-archive.d.ts +4 -0
  34. package/dist/tar/tar-archive.d.ts.map +1 -0
  35. package/dist/tar/tar-archive.js +97 -0
  36. package/dist/tar/tar-archive.js.map +1 -0
  37. package/dist/tar/tar-builder.d.ts +28 -0
  38. package/dist/tar/tar-builder.d.ts.map +1 -0
  39. package/dist/tar/tar-builder.js +38 -0
  40. package/dist/tar/tar-builder.js.map +1 -0
  41. package/dist/tar/tar-format.d.ts +12 -0
  42. package/dist/tar/tar-format.d.ts.map +1 -0
  43. package/dist/tar/tar-format.js +15 -0
  44. package/dist/tar/tar-format.js.map +1 -0
  45. package/dist/tar/tar-loader-types.d.ts +15 -0
  46. package/dist/tar/tar-loader-types.d.ts.map +1 -0
  47. package/dist/tar/tar-loader-types.js +20 -0
  48. package/dist/tar/tar-loader-types.js.map +1 -0
  49. package/dist/tar/tar-loader.cjs +285 -0
  50. package/dist/tar/tar-loader.cjs.map +6 -0
  51. package/dist/tar/tar-loader.d.ts +3 -0
  52. package/dist/tar/tar-loader.d.ts.map +1 -0
  53. package/dist/tar/tar-loader.js +12 -0
  54. package/dist/tar/tar-loader.js.map +1 -0
  55. package/dist/tar/tar-writer.cjs +114 -0
  56. package/dist/tar/tar-writer.cjs.map +6 -0
  57. package/dist/tar/tar-writer.d.ts +20 -0
  58. package/dist/tar/tar-writer.d.ts.map +1 -0
  59. package/dist/tar/tar-writer.js +94 -0
  60. package/dist/tar/tar-writer.js.map +1 -0
  61. package/dist/zip/filesystems/IndexedArchive.d.ts +40 -0
  62. package/dist/zip/filesystems/IndexedArchive.d.ts.map +1 -0
  63. package/dist/zip/filesystems/IndexedArchive.js +99 -0
  64. package/dist/zip/filesystems/IndexedArchive.js.map +1 -0
  65. package/dist/zip/filesystems/zip-filesystem.d.ts +53 -0
  66. package/dist/zip/filesystems/zip-filesystem.d.ts.map +1 -0
  67. package/dist/zip/filesystems/zip-filesystem.js +231 -0
  68. package/dist/zip/filesystems/zip-filesystem.js.map +1 -0
  69. package/dist/zip/hash-file-utility.d.ts +20 -0
  70. package/dist/zip/hash-file-utility.d.ts.map +1 -0
  71. package/dist/zip/hash-file-utility.js +83 -0
  72. package/dist/zip/hash-file-utility.js.map +1 -0
  73. package/dist/zip/index.cjs +4614 -0
  74. package/dist/zip/index.cjs.map +6 -0
  75. package/dist/zip/index.d.ts +18 -0
  76. package/dist/zip/index.d.ts.map +1 -0
  77. package/dist/zip/index.js +14 -0
  78. package/dist/zip/index.js.map +1 -0
  79. package/dist/zip/indexed-zip-writer.cjs +1211 -0
  80. package/dist/zip/indexed-zip-writer.cjs.map +6 -0
  81. package/dist/zip/indexed-zip-writer.d.ts +46 -0
  82. package/dist/zip/indexed-zip-writer.d.ts.map +1 -0
  83. package/dist/zip/indexed-zip-writer.js +229 -0
  84. package/dist/zip/indexed-zip-writer.js.map +1 -0
  85. package/dist/zip/lib/zip-composition.d.ts +37 -0
  86. package/dist/zip/lib/zip-composition.d.ts.map +1 -0
  87. package/dist/zip/lib/zip-composition.js +157 -0
  88. package/dist/zip/lib/zip-composition.js.map +1 -0
  89. package/dist/zip/lib/zip-entry-metadata.d.ts +34 -0
  90. package/dist/zip/lib/zip-entry-metadata.d.ts.map +1 -0
  91. package/dist/zip/lib/zip-entry-metadata.js +132 -0
  92. package/dist/zip/lib/zip-entry-metadata.js.map +1 -0
  93. package/dist/zip/lib/zip-serialization.d.ts +36 -0
  94. package/dist/zip/lib/zip-serialization.d.ts.map +1 -0
  95. package/dist/zip/lib/zip-serialization.js +148 -0
  96. package/dist/zip/lib/zip-serialization.js.map +1 -0
  97. package/dist/zip/lib/zip64-extra-field.d.ts +20 -0
  98. package/dist/zip/lib/zip64-extra-field.d.ts.map +1 -0
  99. package/dist/zip/lib/zip64-extra-field.js +53 -0
  100. package/dist/zip/lib/zip64-extra-field.js.map +1 -0
  101. package/dist/zip/zip-archive-types.d.ts +56 -0
  102. package/dist/zip/zip-archive-types.d.ts.map +1 -0
  103. package/dist/zip/zip-archive-types.js +5 -0
  104. package/dist/zip/zip-archive-types.js.map +1 -0
  105. package/dist/zip/zip-archive.d.ts +101 -0
  106. package/dist/zip/zip-archive.d.ts.map +1 -0
  107. package/dist/zip/zip-archive.js +593 -0
  108. package/dist/zip/zip-archive.js.map +1 -0
  109. package/dist/zip/zip-encode-types.d.ts +41 -0
  110. package/dist/zip/zip-encode-types.d.ts.map +1 -0
  111. package/dist/zip/zip-encode-types.js +5 -0
  112. package/dist/zip/zip-encode-types.js.map +1 -0
  113. package/dist/zip/zip-encode.cjs +1154 -0
  114. package/dist/zip/zip-encode.cjs.map +6 -0
  115. package/dist/zip/zip-encode.d.ts +15 -0
  116. package/dist/zip/zip-encode.d.ts.map +1 -0
  117. package/dist/zip/zip-encode.js +312 -0
  118. package/dist/zip/zip-encode.js.map +1 -0
  119. package/dist/zip/zip-format.d.ts +14 -0
  120. package/dist/zip/zip-format.d.ts.map +1 -0
  121. package/dist/zip/zip-format.js +17 -0
  122. package/dist/zip/zip-format.js.map +1 -0
  123. package/dist/zip/zip-loader-types.d.ts +15 -0
  124. package/dist/zip/zip-loader-types.d.ts.map +1 -0
  125. package/dist/zip/zip-loader-types.js +20 -0
  126. package/dist/zip/zip-loader-types.js.map +1 -0
  127. package/dist/zip/zip-loader.cjs +2681 -0
  128. package/dist/zip/zip-loader.cjs.map +6 -0
  129. package/dist/zip/zip-loader.d.ts +3 -0
  130. package/dist/zip/zip-loader.d.ts.map +1 -0
  131. package/dist/zip/zip-loader.js +38 -0
  132. package/dist/zip/zip-loader.js.map +1 -0
  133. package/dist/zip/zip-writer.cjs +1208 -0
  134. package/dist/zip/zip-writer.cjs.map +6 -0
  135. package/dist/zip/zip-writer.d.ts +40 -0
  136. package/dist/zip/zip-writer.d.ts.map +1 -0
  137. package/dist/zip/zip-writer.js +48 -0
  138. package/dist/zip/zip-writer.js.map +1 -0
  139. package/package.json +88 -4
  140. package/src/index.ts +14 -0
  141. package/src/tar/index.ts +11 -0
  142. package/src/tar/lib/header.ts +82 -0
  143. package/src/tar/lib/tar.ts +160 -0
  144. package/src/tar/lib/types.ts +51 -0
  145. package/src/tar/lib/utils.ts +55 -0
  146. package/src/tar/tar-archive.ts +98 -0
  147. package/src/tar/tar-builder.ts +47 -0
  148. package/src/tar/tar-format.ts +17 -0
  149. package/src/tar/tar-loader-types.ts +36 -0
  150. package/src/tar/tar-loader.ts +17 -0
  151. package/src/tar/tar-writer.ts +102 -0
  152. package/src/zip/filesystems/IndexedArchive.ts +110 -0
  153. package/src/zip/filesystems/zip-filesystem.ts +244 -0
  154. package/src/zip/hash-file-utility.ts +109 -0
  155. package/src/zip/index.ts +38 -0
  156. package/src/zip/indexed-zip-writer.ts +345 -0
  157. package/src/zip/lib/zip-composition.ts +243 -0
  158. package/src/zip/lib/zip-entry-metadata.ts +157 -0
  159. package/src/zip/lib/zip-serialization.ts +206 -0
  160. package/src/zip/lib/zip64-extra-field.ts +84 -0
  161. package/src/zip/zip-archive-types.ts +64 -0
  162. package/src/zip/zip-archive.ts +733 -0
  163. package/src/zip/zip-encode-types.ts +53 -0
  164. package/src/zip/zip-encode.ts +370 -0
  165. package/src/zip/zip-format.ts +19 -0
  166. package/src/zip/zip-loader-types.ts +36 -0
  167. package/src/zip/zip-loader.ts +43 -0
  168. package/src/zip/zip-writer.ts +73 -0
@@ -0,0 +1,109 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import {MD5Hash} from '@loaders.gl/crypto';
6
+ import {
7
+ concatenateArrayBuffers,
8
+ concatenateArrayBuffersFromArray
9
+ } from '@loaders.gl/core/loader-utils';
10
+ import type {ZipEntry} from './zip-archive-types';
11
+
12
+ /**
13
+ * Reads hash file from buffer and returns it in ready-to-use form
14
+ * @param arrayBuffer - buffer containing hash file
15
+ * @returns Map containing hash and offset
16
+ */
17
+ export function parseHashTable(arrayBuffer: ArrayBuffer): Record<string, bigint> {
18
+ if (arrayBuffer.byteLength % 24) throw new Error('Invalid ZIP index length');
19
+ const dataView = new DataView(arrayBuffer);
20
+
21
+ const hashMap: Record<string, bigint> = {};
22
+
23
+ for (let i = 0; i < arrayBuffer.byteLength; i = i + 24) {
24
+ const offset = dataView.getBigUint64(i + 16, true);
25
+ const hash = bufferToHex(arrayBuffer, i, 16);
26
+ if (hash in hashMap) throw new Error('Duplicate ZIP index hash');
27
+ hashMap[hash] = offset;
28
+ }
29
+
30
+ return hashMap;
31
+ }
32
+
33
+ function bufferToHex(buffer: ArrayBuffer, start: number, length: number): string {
34
+ // buffer is an ArrayBuffer
35
+ return [...new Uint8Array(buffer, start, length)]
36
+ .map(x => x.toString(16).padStart(2, '0'))
37
+ .join('');
38
+ }
39
+
40
+ /** item of the file offset list */
41
+ type FileListItem = {
42
+ fileName: string;
43
+ localHeaderOffset: bigint;
44
+ };
45
+
46
+ /**
47
+ * creates hash file that later can be added to the SLPK archive
48
+ * @param zipCDIterator iterator to use
49
+ * @returns ArrayBuffer containing hash file
50
+ */
51
+ export async function composeHashFile(
52
+ zipCDIterator: AsyncIterable<FileListItem | ZipEntry> | Iterable<FileListItem | ZipEntry>
53
+ ): Promise<ArrayBuffer> {
54
+ const md5Hash = new MD5Hash();
55
+ const textEncoder = new TextEncoder();
56
+
57
+ const hashArray: ArrayBuffer[] = [];
58
+
59
+ for await (const cdHeader of zipCDIterator) {
60
+ let filename = ('path' in cdHeader ? cdHeader.path : cdHeader.fileName).split('\\').join('/');
61
+ // I3S edge case. All files should be lower case by spec. However, ArcGIS
62
+ // and official i3s_converter https://github.com/Esri/i3s-spec/blob/master/i3s_converter/i3s_converter_ReadMe.md
63
+ // expect `3dSceneLayer.json.gz` in camel case
64
+ if (filename !== '3dSceneLayer.json.gz') {
65
+ filename = filename.toLowerCase();
66
+ }
67
+ const arrayBuffer = textEncoder.encode(filename).buffer;
68
+ const md5 = await md5Hash.hash(arrayBuffer, 'hex');
69
+ hashArray.push(
70
+ concatenateArrayBuffers(hexStringToBuffer(md5), bigintToBuffer(cdHeader.localHeaderOffset))
71
+ );
72
+ }
73
+
74
+ const bufferArray = hashArray.sort(compareHashes);
75
+
76
+ return concatenateArrayBuffersFromArray(bufferArray);
77
+ }
78
+
79
+ /**
80
+ * Function to compare md5 hashes according to https://github.com/Esri/i3s-spec/blob/master/docs/2.0/slpk_hashtable.pcsl.md
81
+ * @param arrA first hash to compare
82
+ * @param arrB second hash to compare
83
+ * @returns 0 if equal, negative number if a<b, pozitive if a>b
84
+ */
85
+ function compareHashes(arrA: ArrayBuffer, arrB: ArrayBuffer): number {
86
+ const a = new BigUint64Array(arrA);
87
+ const b = new BigUint64Array(arrB);
88
+
89
+ return Number(a[0] === b[0] ? a[1] - b[1] : a[0] - b[0]);
90
+ }
91
+
92
+ /**
93
+ * converts hex string to buffer
94
+ * @param str hex string to convert
95
+ * @returns conversion result
96
+ */
97
+ function hexStringToBuffer(str: string): ArrayBuffer {
98
+ const byteArray = str.match(/../g)?.map(h => parseInt(h, 16));
99
+ return new Uint8Array(byteArray ?? new Array(16)).buffer;
100
+ }
101
+
102
+ /**
103
+ * converts bigint to buffer
104
+ * @param n bigint to convert
105
+ * @returns convertion result
106
+ */
107
+ function bigintToBuffer(n: bigint): ArrayBuffer {
108
+ return new BigUint64Array([n]).buffer;
109
+ }
@@ -0,0 +1,38 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ export {ZipFormat} from './zip-format';
6
+ export {ZipLoader} from './zip-loader-types';
7
+ export type {ZipFileMap, ZipLoaderOptions} from './zip-loader-types';
8
+ export type {ZipWriterFiles, ZipWriterOptions} from './zip-writer';
9
+ export {ZipWriter} from './zip-writer';
10
+ export {encodeIndexedZip} from './indexed-zip-writer';
11
+ export type {IndexedZipFiles, IndexedZipOptions} from './indexed-zip-writer';
12
+
13
+ export {addOneFile, createZip} from './lib/zip-composition';
14
+ export type {ZipCompositionOptions} from './lib/zip-composition';
15
+
16
+ export {IndexedArchive} from './filesystems/IndexedArchive';
17
+ export {parseHashTable, composeHashFile} from './hash-file-utility';
18
+
19
+ export {ZipFileSystem} from './filesystems/zip-filesystem';
20
+ export type {ZipFileStat} from './filesystems/zip-filesystem';
21
+
22
+ export {ZipArchive, openZipArchive} from './zip-archive';
23
+ export type {
24
+ ZipArchiveInput,
25
+ ZipArchiveOptions,
26
+ ZipEntry,
27
+ ZipReadOptions,
28
+ ZipRangeOptions
29
+ } from './zip-archive-types';
30
+
31
+ export {encodeZip, encodeZipInBatches} from './zip-encode';
32
+ export type {
33
+ ZipByteChunk,
34
+ ZipByteSource,
35
+ ZipEncodeEntry,
36
+ ZipEncodeFiles,
37
+ ZipEncodeOptions
38
+ } from './zip-encode-types';
@@ -0,0 +1,345 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import {CRC32Hash, MD5Hash} from '@loaders.gl/crypto';
6
+ import {
7
+ encodeZipLocalHeader,
8
+ encodeZipCentralHeader,
9
+ encodeZipEndRecords
10
+ } from './lib/zip-serialization';
11
+
12
+ /** Already encoded resources. Inputs must remain unchanged while packaging. */
13
+ export type IndexedZipFiles = Readonly<Record<string, ArrayBuffer | Blob>>;
14
+
15
+ /** Configuration for a deterministic STORE ZIP32/ZIP64 with a final MD5 path/offset index. */
16
+ export interface IndexedZipOptions {
17
+ /** Canonical ASCII, nonnumeric name for the generated final index entry. */
18
+ readonly indexPath: string;
19
+ /** Maximum final archive bytes, including headers/index; not a peak-memory limit. */
20
+ readonly maxArchiveBytes: number;
21
+ /** Hash lowercase paths for SLPK; retain case-sensitive paths for 3TZ by default. */
22
+ readonly lowercasePaths?: boolean;
23
+ /** ZIP64 field/end-record policy; defaults to automatic selection. */
24
+ readonly zip64?: 'auto' | 'always' | 'never';
25
+ /** Force ZIP64 when complete output exceeds this byte size, for format-specific profiles. */
26
+ readonly zip64Threshold?: number;
27
+ /** Maximum named entries, including the index; defaults to 100000. */
28
+ readonly maxEntries?: number;
29
+ /** Maximum retained central-directory bytes; defaults to 32 MiB. */
30
+ readonly maxDirectoryBytes?: number;
31
+ /** Cooperative cancellation between block reads and header encodes; not an interrupt for either. */
32
+ readonly signal?: AbortSignal;
33
+ }
34
+
35
+ /** Maximum temporary payload read/copy per block; caller inputs and index metadata are retained. */
36
+ const RESOURCE_CHUNK_BYTES = 64 * 1024;
37
+
38
+ /**
39
+ * Encodes a bounded, deterministic indexed ZIP32/ZIP64 from immutable ArrayBuffers or Blobs.
40
+ * Validates/measures all entries before reading Blobs; hashes canonical ASCII resource paths.
41
+ * Reads resource payloads in bounded blocks into the final buffer, with a checksum pass before each entry.
42
+ * Uses populated local headers, no compression/descriptors/comments, and a fixed timestamp.
43
+ * Cancellation is checked between block reads/encodes; use worker termination to interrupt active work.
44
+ * @param files - Already authored resources, excluding the index generated by this encoder.
45
+ * @param options - Index naming/hash profile and maximum complete archive size.
46
+ * @returns ZIP bytes with the final 24-byte-per-resource MD5/offset index.
47
+ */
48
+ export async function encodeIndexedZip(
49
+ files: IndexedZipFiles,
50
+ options: IndexedZipOptions
51
+ ): Promise<ArrayBuffer> {
52
+ const layout = prepareArchiveLayout(files, options);
53
+ if (layout.archiveBytes > 0xffffffff)
54
+ throw new RangeError('Indexed ZIP buffer capacity exceeded; use encodeIndexedZipInBatches');
55
+ const archive = new Uint8Array(layout.archiveBytes);
56
+ let offset = 0;
57
+ for await (const chunk of encodeArchiveChunks(layout)) {
58
+ archive.set(chunk, offset);
59
+ offset += chunk.byteLength;
60
+ }
61
+ return archive.buffer;
62
+ }
63
+
64
+ /**
65
+ * Yields deterministic indexed ZIP32/ZIP64 chunks with consumer-controlled backpressure.
66
+ * All paths and the complete archive budget are checked on the first pull, before Blob reads
67
+ * or output. Reads/copies payloads in blocks of at most 64 KiB, retaining inputs and index/central
68
+ * metadata without allocating a complete entry or archive buffer. A checksum pass reads each
69
+ * resource before its populated local header; a second pass yields payload blocks on demand.
70
+ * Chunks are byte views; consumers must respect their offsets and lengths. Inputs must stay unchanged. Stop iteration to prevent subsequent reads/encodes.
71
+ * Cancellation is cooperative; callers own discarding partial output and storage finalization.
72
+ * @param files - Already authored resources, excluding the generated index.
73
+ * @param options - Index profile, complete output-size budget, and optional cancellation signal.
74
+ * @returns Local entries followed by the central directory and ZIP end record.
75
+ */
76
+ export async function* encodeIndexedZipInBatches(
77
+ files: IndexedZipFiles,
78
+ options: IndexedZipOptions
79
+ ): AsyncIterable<Uint8Array<ArrayBuffer>> {
80
+ yield* encodeArchiveChunks(prepareArchiveLayout(files, options));
81
+ }
82
+
83
+ /** Captures immutable resource descriptors and validates the complete ZIP32 layout before I/O. */
84
+ function prepareArchiveLayout(files: IndexedZipFiles, options: IndexedZipOptions) {
85
+ const {
86
+ maxArchiveBytes,
87
+ indexPath,
88
+ lowercasePaths = false,
89
+ signal,
90
+ zip64: policy = 'auto',
91
+ zip64Threshold = 0xfffffffe,
92
+ maxEntries = 100000,
93
+ maxDirectoryBytes = 32 * 1024 * 1024
94
+ } = options;
95
+ if (
96
+ !['auto', 'always', 'never'].includes(policy) ||
97
+ !Number.isSafeInteger(zip64Threshold) ||
98
+ zip64Threshold < 0 ||
99
+ !Number.isSafeInteger(maxEntries) ||
100
+ maxEntries < 1 ||
101
+ !Number.isSafeInteger(maxDirectoryBytes) ||
102
+ maxDirectoryBytes < 1
103
+ )
104
+ throw new RangeError('Invalid indexed ZIP policy or metadata limit');
105
+ signal?.throwIfAborted();
106
+ validatePath(indexPath);
107
+ if (/^\d+$/.test(indexPath)) {
108
+ throw new TypeError('Indexed ZIP index path must be nonnumeric to remain the final entry');
109
+ }
110
+ if (!Number.isSafeInteger(maxArchiveBytes) || maxArchiveBytes < 0) {
111
+ throw new RangeError('Indexed ZIP archive byte limit must be a non-negative safe integer');
112
+ }
113
+ // Integer-like object keys follow ECMAScript enumeration order.
114
+ const paths = Object.keys(
115
+ Object.fromEntries(
116
+ Object.keys(files)
117
+ .sort()
118
+ .map(path => [path, true])
119
+ )
120
+ );
121
+ if (paths.length + 1 > maxEntries) throw new RangeError('Indexed ZIP entry limit exceeded');
122
+ const canonicalPaths = paths.map(path => (lowercasePaths ? path.toLowerCase() : path));
123
+ if (new Set(canonicalPaths).size !== paths.length) {
124
+ throw new TypeError('Indexed ZIP contains duplicate canonical paths');
125
+ }
126
+ const resources = paths.map(path => {
127
+ validatePath(path);
128
+ if (
129
+ (lowercasePaths ? path.toLowerCase() : path) ===
130
+ (lowercasePaths ? indexPath.toLowerCase() : indexPath)
131
+ ) {
132
+ throw new TypeError('Indexed ZIP resource uses the reserved index path');
133
+ }
134
+ const data = files[path];
135
+ const byteLength =
136
+ data instanceof ArrayBuffer
137
+ ? (Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, 'byteLength')!.get!.call(
138
+ data
139
+ ) as number)
140
+ : (Object.getOwnPropertyDescriptor(Blob.prototype, 'size')!.get!.call(data) as number);
141
+ return {path, data, byteLength};
142
+ });
143
+ // ZIP32: EOCD + local/central headers + both copies of each ASCII path + index payload.
144
+ const zip32Bytes = resources.reduce(
145
+ (total, resource) => total + 76 + 2 * resource.path.length + resource.byteLength,
146
+ 22 + 76 + 2 * indexPath.length + 24 * resources.length
147
+ );
148
+ const requiresZip64 =
149
+ zip32Bytes > Math.min(zip64Threshold, 0xfffffffe) || resources.length + 1 >= 0xffff;
150
+ if (policy === 'never' && requiresZip64) throw new RangeError('Indexed ZIP requires ZIP64');
151
+ const zip64 = policy === 'always' || requiresZip64;
152
+ const archiveBytes = zip32Bytes + (zip64 ? 48 * (resources.length + 1) + 76 : 0);
153
+ const directoryBytes =
154
+ resources.reduce(
155
+ (total, resource) => total + 46 + resource.path.length,
156
+ 46 + indexPath.length
157
+ ) + (zip64 ? 28 * (resources.length + 1) : 0);
158
+ if (directoryBytes > maxDirectoryBytes)
159
+ throw new RangeError('Indexed ZIP directory byte limit exceeded');
160
+ if (!Number.isSafeInteger(archiveBytes) || archiveBytes > maxArchiveBytes)
161
+ throw new RangeError('Indexed ZIP archive exceeds the configured byte limit');
162
+ return {resources, archiveBytes, indexPath, lowercasePaths, signal, zip64};
163
+ }
164
+
165
+ /** Serializes measured entries lazily, retaining only the index and central-directory records. */
166
+ async function* encodeArchiveChunks(
167
+ layout: ReturnType<typeof prepareArchiveLayout>
168
+ ): AsyncIterable<Uint8Array<ArrayBuffer>> {
169
+ const {resources, archiveBytes, indexPath, lowercasePaths, signal, zip64} = layout;
170
+ const entries: DataView[] = [];
171
+ const centralHeaders: Uint8Array<ArrayBuffer>[] = [];
172
+ const hash = new MD5Hash();
173
+ const digests = new Set<string>();
174
+ let localHeaderOffset = 0;
175
+ for (const resource of resources) {
176
+ signal?.throwIfAborted();
177
+ const checksum = await checksumResource(resource, signal);
178
+ signal?.throwIfAborted();
179
+ const digest = await hash.hash(
180
+ new TextEncoder().encode(lowercasePaths ? resource.path.toLowerCase() : resource.path).buffer,
181
+ 'hex'
182
+ );
183
+ if (digests.has(digest)) throw new Error('Indexed ZIP contains duplicate MD5 hashes');
184
+ digests.add(digest);
185
+ const entry = new DataView(new ArrayBuffer(24));
186
+ for (let index = 0; index < 16; index++) {
187
+ entry.setUint8(index, Number.parseInt(digest.slice(index * 2, index * 2 + 2), 16));
188
+ }
189
+ entry.setBigUint64(16, BigInt(localHeaderOffset), true);
190
+ entries.push(entry);
191
+ signal?.throwIfAborted();
192
+ assertResourceSize(resource);
193
+ const headers = await encodeEntryHeaders(
194
+ resource.path,
195
+ resource.byteLength,
196
+ checksum,
197
+ localHeaderOffset,
198
+ zip64
199
+ );
200
+ signal?.throwIfAborted();
201
+ assertResourceSize(resource);
202
+ centralHeaders.push(headers.centralHeader);
203
+ localHeaderOffset += headers.localHeader.byteLength + resource.byteLength;
204
+ yield headers.localHeader;
205
+ for await (const block of readResourceBlocks(resource, signal)) yield new Uint8Array(block);
206
+ }
207
+ entries.sort(compareIndexEntries);
208
+ const indexData = new Uint8Array(24 * entries.length);
209
+ entries.forEach((entry, index) => indexData.set(new Uint8Array(entry.buffer), index * 24));
210
+ signal?.throwIfAborted();
211
+ const indexResource = {data: indexData.buffer, byteLength: indexData.byteLength};
212
+ const indexChecksum = await checksumResource(indexResource, signal);
213
+ const indexHeaders = await encodeEntryHeaders(
214
+ indexPath,
215
+ indexData.byteLength,
216
+ indexChecksum,
217
+ localHeaderOffset,
218
+ zip64
219
+ );
220
+ signal?.throwIfAborted();
221
+ centralHeaders.push(indexHeaders.centralHeader);
222
+ const centralDirectoryOffset =
223
+ localHeaderOffset + indexHeaders.localHeader.byteLength + indexData.byteLength;
224
+ yield indexHeaders.localHeader;
225
+ for await (const block of readResourceBlocks(indexResource, signal)) yield new Uint8Array(block);
226
+ for (const centralHeader of centralHeaders) {
227
+ signal?.throwIfAborted();
228
+ yield centralHeader;
229
+ }
230
+ signal?.throwIfAborted();
231
+ yield encodeZipEndRecords(
232
+ BigInt(resources.length + 1),
233
+ BigInt(archiveBytes - (zip64 ? 98 : 22) - centralDirectoryOffset),
234
+ BigInt(centralDirectoryOffset),
235
+ zip64
236
+ );
237
+ signal?.throwIfAborted();
238
+ }
239
+
240
+ /** Captured resource size shared by the checksum and payload passes. */
241
+ interface ZipResource {
242
+ /** Immutable caller-owned input, or generated index bytes. */
243
+ readonly data: ArrayBuffer | Blob;
244
+ /** Native byte size measured before any reads or output. */
245
+ readonly byteLength: number;
246
+ }
247
+
248
+ /** Reads/copies one bounded block at a time, checking cancellation and captured sizes. */
249
+ async function* readResourceBlocks(
250
+ resource: ZipResource,
251
+ signal?: AbortSignal
252
+ ): AsyncIterable<ArrayBuffer> {
253
+ signal?.throwIfAborted();
254
+ assertResourceSize(resource);
255
+ for (let offset = 0; offset < resource.byteLength; offset += RESOURCE_CHUNK_BYTES) {
256
+ signal?.throwIfAborted();
257
+ assertResourceSize(resource);
258
+ const end = Math.min(offset + RESOURCE_CHUNK_BYTES, resource.byteLength);
259
+ const block =
260
+ resource.data instanceof ArrayBuffer
261
+ ? ArrayBuffer.prototype.slice.call(resource.data, offset, end)
262
+ : await Blob.prototype.arrayBuffer.call(
263
+ Blob.prototype.slice.call(resource.data, offset, end)
264
+ );
265
+ signal?.throwIfAborted();
266
+ if (block.byteLength !== end - offset) {
267
+ throw new TypeError('Indexed ZIP resource size changed during packaging');
268
+ }
269
+ yield block;
270
+ }
271
+ signal?.throwIfAborted();
272
+ }
273
+
274
+ /** Rejects ArrayBuffer detachment/resizing across asynchronous reads or header encoding. */
275
+ function assertResourceSize(resource: ZipResource): void {
276
+ if (resource.data instanceof ArrayBuffer && resource.data.byteLength !== resource.byteLength) {
277
+ throw new TypeError('Indexed ZIP resource size changed during packaging');
278
+ }
279
+ }
280
+
281
+ /** Calculates CRC-32 incrementally without retaining the checksum pass's payload blocks. */
282
+ async function checksumResource(resource: ZipResource, signal?: AbortSignal): Promise<number> {
283
+ let checksum = 0;
284
+ const hash = new CRC32Hash({
285
+ crypto: {
286
+ /** Captures the final checksum after all input blocks have been consumed. */
287
+ onEnd: (result: {/** Hex-encoded CRC-32 digest. */ hash: string}) => {
288
+ checksum = Number.parseInt(result.hash, 16);
289
+ }
290
+ }
291
+ });
292
+ for await (const _block of hash.hashBatches(readResourceBlocks(resource, signal), 'hex')) {
293
+ signal?.throwIfAborted();
294
+ }
295
+ return checksum;
296
+ }
297
+
298
+ /** Serializes populated STORE headers using the shared native record encoder. */
299
+ async function encodeEntryHeaders(
300
+ path: string,
301
+ byteLength: number,
302
+ checksum: number,
303
+ localHeaderOffset: number,
304
+ zip64: boolean
305
+ ): Promise<{
306
+ /** Populated local header and ASCII resource name. */
307
+ readonly localHeader: Uint8Array<ArrayBuffer>;
308
+ /** Independent central header, safe when the local buffer is transferred. */
309
+ readonly centralHeader: Uint8Array<ArrayBuffer>;
310
+ }> {
311
+ const entry = {
312
+ nameBytes: new TextEncoder().encode(path),
313
+ date: new Date('1980-01-01T00:00:00Z'),
314
+ method: 0 as const,
315
+ flags: 0,
316
+ crc32: checksum,
317
+ size: BigInt(byteLength),
318
+ compressedSize: BigInt(byteLength),
319
+ localHeaderOffset: BigInt(localHeaderOffset),
320
+ zip64
321
+ };
322
+ return {localHeader: encodeZipLocalHeader(entry), centralHeader: encodeZipCentralHeader(entry)};
323
+ }
324
+
325
+ /** Compares MD5 values as two little-endian unsigned 64-bit integers, per the indexed archive specifications. */
326
+ function compareIndexEntries(left: DataView, right: DataView): number {
327
+ for (const offset of [0, 8]) {
328
+ const leftValue = left.getBigUint64(offset, true);
329
+ const rightValue = right.getBigUint64(offset, true);
330
+ if (leftValue !== rightValue) return leftValue < rightValue ? -1 : 1;
331
+ }
332
+ return 0;
333
+ }
334
+
335
+ /** Rejects paths whose bytes or ZIP layout would differ from the measured ASCII layout. */
336
+ function validatePath(path: string): void {
337
+ if (
338
+ path.length > 0xffff ||
339
+ /[^\x20-\x7e]/.test(path) ||
340
+ path.includes('\\') ||
341
+ path.split('/').some(segment => !segment || segment === '.' || segment === '..')
342
+ ) {
343
+ throw new TypeError('Indexed ZIP requires canonical relative ASCII paths');
344
+ }
345
+ }