gitx.do 0.0.1 → 0.0.3

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 (237) hide show
  1. package/dist/cli/commands/blame.d.ts +259 -0
  2. package/dist/cli/commands/blame.d.ts.map +1 -0
  3. package/dist/cli/commands/blame.js +609 -0
  4. package/dist/cli/commands/blame.js.map +1 -0
  5. package/dist/cli/commands/branch.d.ts +249 -0
  6. package/dist/cli/commands/branch.d.ts.map +1 -0
  7. package/dist/cli/commands/branch.js +693 -0
  8. package/dist/cli/commands/branch.js.map +1 -0
  9. package/dist/cli/commands/commit.d.ts +182 -0
  10. package/dist/cli/commands/commit.d.ts.map +1 -0
  11. package/dist/cli/commands/commit.js +437 -0
  12. package/dist/cli/commands/commit.js.map +1 -0
  13. package/dist/cli/commands/diff.d.ts +464 -0
  14. package/dist/cli/commands/diff.d.ts.map +1 -0
  15. package/dist/cli/commands/diff.js +958 -0
  16. package/dist/cli/commands/diff.js.map +1 -0
  17. package/dist/cli/commands/log.d.ts +239 -0
  18. package/dist/cli/commands/log.d.ts.map +1 -0
  19. package/dist/cli/commands/log.js +535 -0
  20. package/dist/cli/commands/log.js.map +1 -0
  21. package/dist/cli/commands/review.d.ts +457 -0
  22. package/dist/cli/commands/review.d.ts.map +1 -0
  23. package/dist/cli/commands/review.js +533 -0
  24. package/dist/cli/commands/review.js.map +1 -0
  25. package/dist/cli/commands/status.d.ts +269 -0
  26. package/dist/cli/commands/status.d.ts.map +1 -0
  27. package/dist/cli/commands/status.js +493 -0
  28. package/dist/cli/commands/status.js.map +1 -0
  29. package/dist/cli/commands/web.d.ts +199 -0
  30. package/dist/cli/commands/web.d.ts.map +1 -0
  31. package/dist/cli/commands/web.js +696 -0
  32. package/dist/cli/commands/web.js.map +1 -0
  33. package/dist/cli/fs-adapter.d.ts +656 -0
  34. package/dist/cli/fs-adapter.d.ts.map +1 -0
  35. package/dist/cli/fs-adapter.js +1179 -0
  36. package/dist/cli/fs-adapter.js.map +1 -0
  37. package/dist/cli/index.d.ts +387 -0
  38. package/dist/cli/index.d.ts.map +1 -0
  39. package/dist/cli/index.js +523 -0
  40. package/dist/cli/index.js.map +1 -0
  41. package/dist/cli/ui/components/DiffView.d.ts +7 -0
  42. package/dist/cli/ui/components/DiffView.d.ts.map +1 -0
  43. package/dist/cli/ui/components/DiffView.js +11 -0
  44. package/dist/cli/ui/components/DiffView.js.map +1 -0
  45. package/dist/cli/ui/components/ErrorDisplay.d.ts +6 -0
  46. package/dist/cli/ui/components/ErrorDisplay.d.ts.map +1 -0
  47. package/dist/cli/ui/components/ErrorDisplay.js +11 -0
  48. package/dist/cli/ui/components/ErrorDisplay.js.map +1 -0
  49. package/dist/cli/ui/components/FuzzySearch.d.ts +9 -0
  50. package/dist/cli/ui/components/FuzzySearch.d.ts.map +1 -0
  51. package/dist/cli/ui/components/FuzzySearch.js +12 -0
  52. package/dist/cli/ui/components/FuzzySearch.js.map +1 -0
  53. package/dist/cli/ui/components/LoadingSpinner.d.ts +6 -0
  54. package/dist/cli/ui/components/LoadingSpinner.d.ts.map +1 -0
  55. package/dist/cli/ui/components/LoadingSpinner.js +10 -0
  56. package/dist/cli/ui/components/LoadingSpinner.js.map +1 -0
  57. package/dist/cli/ui/components/NavigationList.d.ts +9 -0
  58. package/dist/cli/ui/components/NavigationList.d.ts.map +1 -0
  59. package/dist/cli/ui/components/NavigationList.js +11 -0
  60. package/dist/cli/ui/components/NavigationList.js.map +1 -0
  61. package/dist/cli/ui/components/ScrollableContent.d.ts +8 -0
  62. package/dist/cli/ui/components/ScrollableContent.d.ts.map +1 -0
  63. package/dist/cli/ui/components/ScrollableContent.js +11 -0
  64. package/dist/cli/ui/components/ScrollableContent.js.map +1 -0
  65. package/dist/cli/ui/components/index.d.ts +7 -0
  66. package/dist/cli/ui/components/index.d.ts.map +1 -0
  67. package/dist/cli/ui/components/index.js +9 -0
  68. package/dist/cli/ui/components/index.js.map +1 -0
  69. package/dist/cli/ui/terminal-ui.d.ts +52 -0
  70. package/dist/cli/ui/terminal-ui.d.ts.map +1 -0
  71. package/dist/cli/ui/terminal-ui.js +121 -0
  72. package/dist/cli/ui/terminal-ui.js.map +1 -0
  73. package/dist/durable-object/object-store.d.ts +401 -23
  74. package/dist/durable-object/object-store.d.ts.map +1 -1
  75. package/dist/durable-object/object-store.js +414 -25
  76. package/dist/durable-object/object-store.js.map +1 -1
  77. package/dist/durable-object/schema.d.ts +188 -0
  78. package/dist/durable-object/schema.d.ts.map +1 -1
  79. package/dist/durable-object/schema.js +160 -0
  80. package/dist/durable-object/schema.js.map +1 -1
  81. package/dist/durable-object/wal.d.ts +336 -31
  82. package/dist/durable-object/wal.d.ts.map +1 -1
  83. package/dist/durable-object/wal.js +272 -27
  84. package/dist/durable-object/wal.js.map +1 -1
  85. package/dist/index.d.ts +379 -3
  86. package/dist/index.d.ts.map +1 -1
  87. package/dist/index.js +379 -7
  88. package/dist/index.js.map +1 -1
  89. package/dist/mcp/adapter.d.ts +579 -38
  90. package/dist/mcp/adapter.d.ts.map +1 -1
  91. package/dist/mcp/adapter.js +426 -33
  92. package/dist/mcp/adapter.js.map +1 -1
  93. package/dist/mcp/sandbox.d.ts +532 -29
  94. package/dist/mcp/sandbox.d.ts.map +1 -1
  95. package/dist/mcp/sandbox.js +389 -22
  96. package/dist/mcp/sandbox.js.map +1 -1
  97. package/dist/mcp/sdk-adapter.d.ts +478 -56
  98. package/dist/mcp/sdk-adapter.d.ts.map +1 -1
  99. package/dist/mcp/sdk-adapter.js +346 -44
  100. package/dist/mcp/sdk-adapter.js.map +1 -1
  101. package/dist/mcp/tools.d.ts +445 -30
  102. package/dist/mcp/tools.d.ts.map +1 -1
  103. package/dist/mcp/tools.js +363 -33
  104. package/dist/mcp/tools.js.map +1 -1
  105. package/dist/ops/blame.d.ts +424 -21
  106. package/dist/ops/blame.d.ts.map +1 -1
  107. package/dist/ops/blame.js +303 -20
  108. package/dist/ops/blame.js.map +1 -1
  109. package/dist/ops/branch.d.ts +583 -32
  110. package/dist/ops/branch.d.ts.map +1 -1
  111. package/dist/ops/branch.js +365 -23
  112. package/dist/ops/branch.js.map +1 -1
  113. package/dist/ops/commit-traversal.d.ts +164 -24
  114. package/dist/ops/commit-traversal.d.ts.map +1 -1
  115. package/dist/ops/commit-traversal.js +68 -2
  116. package/dist/ops/commit-traversal.js.map +1 -1
  117. package/dist/ops/commit.d.ts +387 -53
  118. package/dist/ops/commit.d.ts.map +1 -1
  119. package/dist/ops/commit.js +249 -29
  120. package/dist/ops/commit.js.map +1 -1
  121. package/dist/ops/merge-base.d.ts +195 -21
  122. package/dist/ops/merge-base.d.ts.map +1 -1
  123. package/dist/ops/merge-base.js +122 -12
  124. package/dist/ops/merge-base.js.map +1 -1
  125. package/dist/ops/merge.d.ts +600 -130
  126. package/dist/ops/merge.d.ts.map +1 -1
  127. package/dist/ops/merge.js +408 -60
  128. package/dist/ops/merge.js.map +1 -1
  129. package/dist/ops/tag.d.ts +67 -2
  130. package/dist/ops/tag.d.ts.map +1 -1
  131. package/dist/ops/tag.js +42 -1
  132. package/dist/ops/tag.js.map +1 -1
  133. package/dist/ops/tree-builder.d.ts +102 -6
  134. package/dist/ops/tree-builder.d.ts.map +1 -1
  135. package/dist/ops/tree-builder.js +30 -5
  136. package/dist/ops/tree-builder.js.map +1 -1
  137. package/dist/ops/tree-diff.d.ts +50 -2
  138. package/dist/ops/tree-diff.d.ts.map +1 -1
  139. package/dist/ops/tree-diff.js +50 -2
  140. package/dist/ops/tree-diff.js.map +1 -1
  141. package/dist/pack/delta.d.ts +211 -39
  142. package/dist/pack/delta.d.ts.map +1 -1
  143. package/dist/pack/delta.js +232 -46
  144. package/dist/pack/delta.js.map +1 -1
  145. package/dist/pack/format.d.ts +390 -28
  146. package/dist/pack/format.d.ts.map +1 -1
  147. package/dist/pack/format.js +344 -33
  148. package/dist/pack/format.js.map +1 -1
  149. package/dist/pack/full-generation.d.ts +313 -28
  150. package/dist/pack/full-generation.d.ts.map +1 -1
  151. package/dist/pack/full-generation.js +238 -19
  152. package/dist/pack/full-generation.js.map +1 -1
  153. package/dist/pack/generation.d.ts +346 -23
  154. package/dist/pack/generation.d.ts.map +1 -1
  155. package/dist/pack/generation.js +269 -21
  156. package/dist/pack/generation.js.map +1 -1
  157. package/dist/pack/index.d.ts +407 -86
  158. package/dist/pack/index.d.ts.map +1 -1
  159. package/dist/pack/index.js +351 -70
  160. package/dist/pack/index.js.map +1 -1
  161. package/dist/refs/branch.d.ts +517 -71
  162. package/dist/refs/branch.d.ts.map +1 -1
  163. package/dist/refs/branch.js +410 -26
  164. package/dist/refs/branch.js.map +1 -1
  165. package/dist/refs/storage.d.ts +610 -57
  166. package/dist/refs/storage.d.ts.map +1 -1
  167. package/dist/refs/storage.js +481 -29
  168. package/dist/refs/storage.js.map +1 -1
  169. package/dist/refs/tag.d.ts +677 -67
  170. package/dist/refs/tag.d.ts.map +1 -1
  171. package/dist/refs/tag.js +497 -30
  172. package/dist/refs/tag.js.map +1 -1
  173. package/dist/storage/lru-cache.d.ts +556 -53
  174. package/dist/storage/lru-cache.d.ts.map +1 -1
  175. package/dist/storage/lru-cache.js +439 -36
  176. package/dist/storage/lru-cache.js.map +1 -1
  177. package/dist/storage/object-index.d.ts +483 -38
  178. package/dist/storage/object-index.d.ts.map +1 -1
  179. package/dist/storage/object-index.js +388 -22
  180. package/dist/storage/object-index.js.map +1 -1
  181. package/dist/storage/r2-pack.d.ts +957 -94
  182. package/dist/storage/r2-pack.d.ts.map +1 -1
  183. package/dist/storage/r2-pack.js +756 -48
  184. package/dist/storage/r2-pack.js.map +1 -1
  185. package/dist/tiered/cdc-pipeline.d.ts +1610 -38
  186. package/dist/tiered/cdc-pipeline.d.ts.map +1 -1
  187. package/dist/tiered/cdc-pipeline.js +1131 -22
  188. package/dist/tiered/cdc-pipeline.js.map +1 -1
  189. package/dist/tiered/migration.d.ts +903 -41
  190. package/dist/tiered/migration.d.ts.map +1 -1
  191. package/dist/tiered/migration.js +646 -24
  192. package/dist/tiered/migration.js.map +1 -1
  193. package/dist/tiered/parquet-writer.d.ts +944 -47
  194. package/dist/tiered/parquet-writer.d.ts.map +1 -1
  195. package/dist/tiered/parquet-writer.js +667 -39
  196. package/dist/tiered/parquet-writer.js.map +1 -1
  197. package/dist/tiered/read-path.d.ts +728 -34
  198. package/dist/tiered/read-path.d.ts.map +1 -1
  199. package/dist/tiered/read-path.js +310 -27
  200. package/dist/tiered/read-path.js.map +1 -1
  201. package/dist/types/objects.d.ts +457 -0
  202. package/dist/types/objects.d.ts.map +1 -1
  203. package/dist/types/objects.js +305 -4
  204. package/dist/types/objects.js.map +1 -1
  205. package/dist/types/storage.d.ts +407 -35
  206. package/dist/types/storage.d.ts.map +1 -1
  207. package/dist/types/storage.js +27 -3
  208. package/dist/types/storage.js.map +1 -1
  209. package/dist/utils/hash.d.ts +133 -12
  210. package/dist/utils/hash.d.ts.map +1 -1
  211. package/dist/utils/hash.js +133 -12
  212. package/dist/utils/hash.js.map +1 -1
  213. package/dist/utils/sha1.d.ts +102 -9
  214. package/dist/utils/sha1.d.ts.map +1 -1
  215. package/dist/utils/sha1.js +114 -11
  216. package/dist/utils/sha1.js.map +1 -1
  217. package/dist/wire/capabilities.d.ts +896 -88
  218. package/dist/wire/capabilities.d.ts.map +1 -1
  219. package/dist/wire/capabilities.js +566 -62
  220. package/dist/wire/capabilities.js.map +1 -1
  221. package/dist/wire/pkt-line.d.ts +293 -15
  222. package/dist/wire/pkt-line.d.ts.map +1 -1
  223. package/dist/wire/pkt-line.js +251 -15
  224. package/dist/wire/pkt-line.js.map +1 -1
  225. package/dist/wire/receive-pack.d.ts +814 -64
  226. package/dist/wire/receive-pack.d.ts.map +1 -1
  227. package/dist/wire/receive-pack.js +542 -41
  228. package/dist/wire/receive-pack.js.map +1 -1
  229. package/dist/wire/smart-http.d.ts +575 -97
  230. package/dist/wire/smart-http.d.ts.map +1 -1
  231. package/dist/wire/smart-http.js +337 -46
  232. package/dist/wire/smart-http.js.map +1 -1
  233. package/dist/wire/upload-pack.d.ts +492 -98
  234. package/dist/wire/upload-pack.d.ts.map +1 -1
  235. package/dist/wire/upload-pack.js +347 -59
  236. package/dist/wire/upload-pack.js.map +1 -1
  237. package/package.json +10 -2
@@ -1,84 +1,446 @@
1
1
  /**
2
- * Git Packfile Format Implementation
2
+ * @fileoverview Git Packfile Format Implementation
3
3
  *
4
- * The packfile format is used by git for efficient storage and transfer of objects.
5
- * Format:
6
- * - 4 bytes: "PACK" signature
7
- * - 4 bytes: version number (network byte order, big-endian)
8
- * - 4 bytes: number of objects (network byte order)
9
- * - N objects: each object has header + compressed data
10
- * - 20 bytes: SHA-1 checksum of all preceding content
4
+ * This module implements the Git packfile format specification, providing utilities
5
+ * for creating, parsing, and manipulating Git packfiles. Packfiles are Git's primary
6
+ * mechanism for efficient storage and network transfer of repository objects.
11
7
  *
12
- * Object header encoding:
8
+ * ## Packfile Structure
9
+ *
10
+ * A packfile consists of:
11
+ * - **Header (12 bytes)**:
12
+ * - 4 bytes: "PACK" signature
13
+ * - 4 bytes: version number (network byte order, big-endian) - currently version 2
14
+ * - 4 bytes: number of objects (network byte order)
15
+ * - **Object entries (variable length)**:
16
+ * - Each object has a variable-length header followed by zlib-compressed data
17
+ * - **Trailer (20 bytes)**:
18
+ * - SHA-1 checksum of all preceding content
19
+ *
20
+ * ## Object Header Encoding
21
+ *
22
+ * The object header uses a variable-length encoding:
13
23
  * - First byte: (MSB) continuation bit | 3-bit type | 4-bit size LSB
14
- * - Subsequent bytes: (MSB) continuation bit | 7-bit size
24
+ * - Subsequent bytes: (MSB) continuation bit | 7-bit size continuation
25
+ *
26
+ * ## Supported Object Types
27
+ *
28
+ * | Type Code | Name | Description |
29
+ * |-----------|-----------|------------------------------------------------|
30
+ * | 1 | commit | A commit object |
31
+ * | 2 | tree | A tree object (directory listing) |
32
+ * | 3 | blob | A blob object (file content) |
33
+ * | 4 | tag | An annotated tag object |
34
+ * | 6 | ofs_delta | Delta referencing base by offset |
35
+ * | 7 | ref_delta | Delta referencing base by SHA-1 |
36
+ *
37
+ * @module pack/format
38
+ * @see {@link https://git-scm.com/docs/pack-format} Git Pack Format Documentation
15
39
  *
16
- * Object types:
17
- * - 1: commit
18
- * - 2: tree
19
- * - 3: blob
20
- * - 4: tag
21
- * - 6: ofs_delta (offset delta)
22
- * - 7: ref_delta (reference delta)
40
+ * @example
41
+ * // Creating a simple packfile
42
+ * import { createPackfile, PackableObject } from './format';
43
+ *
44
+ * const objects: PackableObject[] = [
45
+ * { type: 'blob', data: new TextEncoder().encode('Hello, World!') }
46
+ * ];
47
+ *
48
+ * const packfile = createPackfile(objects);
49
+ * // packfile is now a Uint8Array containing the complete packfile
50
+ */
51
+ /**
52
+ * The 4-byte ASCII signature that identifies a valid packfile.
53
+ * Every packfile must begin with these bytes: 0x50 0x41 0x43 0x4b ("PACK").
54
+ *
55
+ * @constant {string}
56
+ * @example
57
+ * // Validate packfile signature
58
+ * const signature = String.fromCharCode(...packData.slice(0, 4));
59
+ * if (signature !== PACK_SIGNATURE) {
60
+ * throw new Error('Invalid packfile');
61
+ * }
23
62
  */
24
63
  export declare const PACK_SIGNATURE = "PACK";
64
+ /**
65
+ * The packfile version number supported by this implementation.
66
+ * Currently, only version 2 is widely used and supported.
67
+ *
68
+ * @constant {number}
69
+ */
25
70
  export declare const PACK_VERSION = 2;
71
+ /**
72
+ * Enumeration of Git pack object types.
73
+ *
74
+ * These values are used in the packfile header to identify the type of each object.
75
+ * Note that types 0 and 5 are reserved/unused in the Git pack format.
76
+ *
77
+ * @description Represents the different types of objects that can be stored in a Git packfile.
78
+ * Delta types (OFS_DELTA and REF_DELTA) are used for efficient storage by referencing
79
+ * a base object and storing only the differences.
80
+ *
81
+ * @enum {number}
82
+ *
83
+ * @example
84
+ * // Check if an object is a delta type
85
+ * function isDelta(type: PackObjectType): boolean {
86
+ * return type === PackObjectType.OBJ_OFS_DELTA || type === PackObjectType.OBJ_REF_DELTA;
87
+ * }
88
+ */
26
89
  export declare enum PackObjectType {
90
+ /** A commit object containing tree reference, parent commits, author, and message */
27
91
  OBJ_COMMIT = 1,
92
+ /** A tree object representing a directory structure */
28
93
  OBJ_TREE = 2,
94
+ /** A blob object containing file content */
29
95
  OBJ_BLOB = 3,
96
+ /** An annotated tag object */
30
97
  OBJ_TAG = 4,
98
+ /** An offset delta - references base object by byte offset within the packfile */
31
99
  OBJ_OFS_DELTA = 6,
100
+ /** A reference delta - references base object by its SHA-1 hash */
32
101
  OBJ_REF_DELTA = 7
33
102
  }
103
+ /**
104
+ * Converts a PackObjectType enum value to its string representation.
105
+ *
106
+ * @description Converts numeric pack object types to their human-readable string names.
107
+ * This is useful for logging, debugging, and when interfacing with Git's loose object format.
108
+ *
109
+ * @param {PackObjectType} type - The numeric pack object type to convert
110
+ * @returns {string} The string name of the object type ('commit', 'tree', 'blob', 'tag', 'ofs_delta', or 'ref_delta')
111
+ * @throws {Error} If the type is not a valid PackObjectType value
112
+ *
113
+ * @example
114
+ * // Convert type for display
115
+ * const type = PackObjectType.OBJ_BLOB;
116
+ * console.log(`Object type: ${packObjectTypeToString(type)}`); // "Object type: blob"
117
+ *
118
+ * @example
119
+ * // Use in error messages
120
+ * function validateObject(type: PackObjectType, data: Uint8Array) {
121
+ * if (data.length === 0) {
122
+ * throw new Error(`Empty ${packObjectTypeToString(type)} object`);
123
+ * }
124
+ * }
125
+ */
34
126
  export declare function packObjectTypeToString(type: PackObjectType): string;
127
+ /**
128
+ * Converts a string object type name to its PackObjectType enum value.
129
+ *
130
+ * @description Parses a string object type name and returns the corresponding enum value.
131
+ * This is useful when reading Git loose objects or configuration files that use string type names.
132
+ * Note: Delta types ('ofs_delta', 'ref_delta') are not supported as they are not valid
133
+ * standalone object types.
134
+ *
135
+ * @param {string} str - The string type name ('commit', 'tree', 'blob', or 'tag')
136
+ * @returns {PackObjectType} The corresponding PackObjectType enum value
137
+ * @throws {Error} If the string does not match a valid base object type
138
+ *
139
+ * @example
140
+ * // Parse type from Git object
141
+ * const typeStr = 'blob';
142
+ * const type = stringToPackObjectType(typeStr);
143
+ * // type === PackObjectType.OBJ_BLOB
144
+ *
145
+ * @example
146
+ * // Error handling for invalid types
147
+ * try {
148
+ * const type = stringToPackObjectType('invalid');
149
+ * } catch (e) {
150
+ * console.error('Unknown object type');
151
+ * }
152
+ */
35
153
  export declare function stringToPackObjectType(str: string): PackObjectType;
154
+ /**
155
+ * Encodes a non-negative integer using variable-length integer encoding.
156
+ *
157
+ * @description Uses Git's varint encoding scheme where each byte encodes 7 bits of the value,
158
+ * with the MSB (most significant bit) serving as a continuation flag. If the MSB is set (1),
159
+ * more bytes follow; if clear (0), this is the last byte.
160
+ *
161
+ * The encoding is little-endian: least significant bits come first. This allows efficient
162
+ * encoding of small values (1 byte for values 0-127) while supporting arbitrarily large values.
163
+ *
164
+ * @param {number} value - A non-negative integer to encode (must be >= 0)
165
+ * @returns {Uint8Array} The variable-length encoded bytes
166
+ *
167
+ * @example
168
+ * // Encode small value (fits in 1 byte)
169
+ * const encoded = encodeVarint(100);
170
+ * // encoded = Uint8Array [100] (0x64, no continuation bit)
171
+ *
172
+ * @example
173
+ * // Encode larger value (requires multiple bytes)
174
+ * const encoded = encodeVarint(300);
175
+ * // encoded = Uint8Array [172, 2] (0xAC with continuation, 0x02)
176
+ * // 300 = 0b100101100 = (0101100 | continuation) + (10)
177
+ */
36
178
  export declare function encodeVarint(value: number): Uint8Array;
179
+ /**
180
+ * Decodes a variable-length integer from a byte buffer.
181
+ *
182
+ * @description Reads and decodes a varint starting at the specified offset. The encoding uses
183
+ * 7 bits per byte for the value, with the MSB as a continuation flag. This is the inverse
184
+ * operation of {@link encodeVarint}.
185
+ *
186
+ * **Important Notes:**
187
+ * - Maximum supported varint length is 10 bytes (enough for 64-bit values)
188
+ * - Throws if data ends unexpectedly before varint is complete
189
+ * - Throws if varint exceeds maximum length (likely corrupted data)
190
+ *
191
+ * @param {Uint8Array} data - The byte buffer containing the encoded varint
192
+ * @param {number} offset - The starting position in the buffer
193
+ * @returns {{ value: number; bytesRead: number }} Object containing the decoded value and number of bytes consumed
194
+ * @throws {Error} If unexpected end of data or varint exceeds maximum length
195
+ *
196
+ * @example
197
+ * // Decode a varint from a buffer
198
+ * const buffer = new Uint8Array([172, 2, 0, 0]); // 300 encoded + extra bytes
199
+ * const { value, bytesRead } = decodeVarint(buffer, 0);
200
+ * // value === 300, bytesRead === 2
201
+ *
202
+ * @example
203
+ * // Decode multiple varints
204
+ * const buffer = new Uint8Array([100, 172, 2]);
205
+ * let offset = 0;
206
+ * const first = decodeVarint(buffer, offset); // value: 100, bytesRead: 1
207
+ * offset += first.bytesRead;
208
+ * const second = decodeVarint(buffer, offset); // value: 300, bytesRead: 2
209
+ */
37
210
  export declare function decodeVarint(data: Uint8Array, offset: number): {
38
211
  value: number;
39
212
  bytesRead: number;
40
213
  };
41
214
  /**
42
- * Encode object type and size into pack object header format
215
+ * Encodes object type and uncompressed size into a pack object header.
216
+ *
217
+ * @description Creates the variable-length header that precedes each object in a packfile.
218
+ * The header encodes both the object type (3 bits) and the uncompressed data size.
219
+ *
220
+ * **Header Format:**
221
+ * - First byte: `[continuation][type:3][size:4]` - MSB is continuation flag, then 3-bit type, then 4 LSBs of size
222
+ * - Subsequent bytes: `[continuation][size:7]` - MSB is continuation flag, then 7 bits of size
223
+ *
224
+ * This encoding allows:
225
+ * - Sizes 0-15: 1 byte
226
+ * - Sizes 16-2047: 2 bytes
227
+ * - Larger sizes: additional bytes as needed
228
+ *
229
+ * @param {PackObjectType} type - The object type (1-4 for base types, 6-7 for deltas)
230
+ * @param {number} size - The uncompressed object size in bytes
231
+ * @returns {Uint8Array} The encoded header bytes
232
+ *
233
+ * @example
234
+ * // Encode a small blob object
235
+ * const header = encodeTypeAndSize(PackObjectType.OBJ_BLOB, 10);
236
+ * // header[0] = (3 << 4) | 10 = 0x3A (type=blob, size=10, no continuation)
43
237
  *
44
- * First byte: MSB continuation bit | 3-bit type | 4-bit size LSB
45
- * Subsequent bytes: MSB continuation bit | 7-bit size continuation
238
+ * @example
239
+ * // Encode a larger object (size requires continuation)
240
+ * const header = encodeTypeAndSize(PackObjectType.OBJ_COMMIT, 256);
241
+ * // First byte has type and low 4 bits of size, with continuation
242
+ * // Second byte has remaining size bits
46
243
  */
47
244
  export declare function encodeTypeAndSize(type: PackObjectType, size: number): Uint8Array;
245
+ /**
246
+ * Decodes object type and size from a pack object header.
247
+ *
248
+ * @description Parses the variable-length header at the beginning of each packed object.
249
+ * This is the inverse operation of {@link encodeTypeAndSize}.
250
+ *
251
+ * **Decoding Process:**
252
+ * 1. Read first byte to get type (bits 4-6) and initial size (bits 0-3)
253
+ * 2. If MSB is set, read continuation bytes (7 bits each) for remaining size
254
+ * 3. Return the decoded type, size, and total bytes consumed
255
+ *
256
+ * **Important Notes:**
257
+ * - Maximum header length is 10 bytes (prevents infinite loops on corrupted data)
258
+ * - Throws if offset is beyond data bounds
259
+ * - Throws if data ends before header is complete
260
+ *
261
+ * @param {Uint8Array} data - The packfile data buffer
262
+ * @param {number} offset - Starting offset of the object header
263
+ * @returns {{ type: PackObjectType; size: number; bytesRead: number }} Decoded type, uncompressed size, and bytes consumed
264
+ * @throws {Error} If offset is out of bounds or header data is truncated/corrupted
265
+ *
266
+ * @example
267
+ * // Decode an object header
268
+ * const packData = getPackfileData();
269
+ * let offset = 12; // Skip 12-byte pack header
270
+ *
271
+ * const { type, size, bytesRead } = decodeTypeAndSize(packData, offset);
272
+ * console.log(`Object type: ${packObjectTypeToString(type)}, size: ${size}`);
273
+ * offset += bytesRead; // Move to start of compressed data
274
+ */
48
275
  export declare function decodeTypeAndSize(data: Uint8Array, offset: number): {
49
276
  type: PackObjectType;
50
277
  size: number;
51
278
  bytesRead: number;
52
279
  };
280
+ /**
281
+ * Represents the parsed 12-byte header of a Git packfile.
282
+ *
283
+ * @description The pack header contains essential metadata about the packfile:
284
+ * - The signature validates this is a genuine packfile
285
+ * - The version indicates the format version (currently always 2)
286
+ * - The object count tells how many objects follow
287
+ *
288
+ * @interface PackHeader
289
+ *
290
+ * @example
291
+ * const header: PackHeader = parsePackHeader(packData);
292
+ * console.log(`Pack contains ${header.objectCount} objects`);
293
+ */
53
294
  export interface PackHeader {
295
+ /** The 4-byte signature string, should always be "PACK" */
54
296
  signature: string;
297
+ /** The format version number (currently always 2) */
55
298
  version: number;
299
+ /** Total number of objects in the packfile */
56
300
  objectCount: number;
57
301
  }
58
302
  /**
59
- * Parse pack file header
60
- * @param data - The packfile data
61
- * @returns Parsed header information
303
+ * Parses and validates the 12-byte header of a Git packfile.
304
+ *
305
+ * @description Reads the first 12 bytes of a packfile and validates:
306
+ * 1. The signature is "PACK"
307
+ * 2. The version is 2 (only supported version)
308
+ * 3. Extracts the object count
309
+ *
310
+ * This should be called first when processing a packfile to understand
311
+ * its structure and validate basic integrity.
312
+ *
313
+ * @param {Uint8Array} data - The packfile data (at least 12 bytes)
314
+ * @returns {PackHeader} Parsed header with signature, version, and object count
315
+ * @throws {Error} If data is too short (< 12 bytes)
316
+ * @throws {Error} If signature is not "PACK"
317
+ * @throws {Error} If version is not 2
318
+ *
319
+ * @example
320
+ * // Parse a packfile header
321
+ * const packData = await readPackfile('objects/pack/pack-abc123.pack');
322
+ * const header = parsePackHeader(packData);
323
+ *
324
+ * console.log(`Packfile version: ${header.version}`);
325
+ * console.log(`Contains ${header.objectCount} objects`);
326
+ *
327
+ * @example
328
+ * // Error handling for invalid packfile
329
+ * try {
330
+ * const header = parsePackHeader(suspectData);
331
+ * } catch (e) {
332
+ * console.error('Not a valid packfile:', e.message);
333
+ * }
62
334
  */
63
335
  export declare function parsePackHeader(data: Uint8Array): PackHeader;
336
+ /**
337
+ * Represents a parsed pack object header (without the actual data).
338
+ *
339
+ * @description Contains the metadata extracted from a pack object's header.
340
+ * This is useful when scanning through a packfile to index its contents
341
+ * without fully decompressing each object.
342
+ *
343
+ * @interface ParsedPackObject
344
+ */
64
345
  export interface ParsedPackObject {
346
+ /** The object type (commit, tree, blob, tag, or delta types) */
65
347
  type: PackObjectType;
348
+ /** The uncompressed size of the object data in bytes */
66
349
  size: number;
350
+ /** Number of bytes consumed by the header (for offset calculations) */
67
351
  headerSize: number;
68
352
  }
69
353
  /**
70
- * Parse individual pack object header
71
- * Note: This only parses the header, not the compressed data
354
+ * Parses an individual pack object header at the specified offset.
355
+ *
356
+ * @description Extracts the object type and uncompressed size from the header
357
+ * at the given offset. This is useful for scanning/indexing packfiles.
358
+ *
359
+ * **Important Notes:**
360
+ * - This only parses the header, not the compressed data following it
361
+ * - For delta objects, you'll need additional parsing (base offset/SHA)
362
+ * - Use `headerSize` to calculate where the compressed data begins
363
+ *
364
+ * @param {Uint8Array} data - The packfile data buffer
365
+ * @param {number} offset - Byte offset where the object header starts
366
+ * @returns {ParsedPackObject} Object containing type, size, and header size
367
+ * @throws {Error} If offset is out of bounds or header is malformed
368
+ *
369
+ * @example
370
+ * // Scan through all objects in a packfile
371
+ * const header = parsePackHeader(packData);
372
+ * let offset = 12; // After pack header
373
+ *
374
+ * for (let i = 0; i < header.objectCount; i++) {
375
+ * const obj = parsePackObject(packData, offset);
376
+ * console.log(`Object ${i}: type=${obj.type}, size=${obj.size}`);
377
+ * // Skip header + compressed data (need to decompress to find boundary)
378
+ * offset += obj.headerSize;
379
+ * // ... decompress and skip compressed data ...
380
+ * }
72
381
  */
73
382
  export declare function parsePackObject(data: Uint8Array, offset: number): ParsedPackObject;
383
+ /**
384
+ * Represents an object to be packed into a packfile.
385
+ *
386
+ * @description This is the input format for {@link createPackfile}. Each object
387
+ * consists of a type string and the raw (uncompressed) object data. The data
388
+ * should be the full object content without the Git object header prefix.
389
+ *
390
+ * @interface PackableObject
391
+ *
392
+ * @example
393
+ * // Create a blob object for a file
394
+ * const blobObject: PackableObject = {
395
+ * type: 'blob',
396
+ * data: new TextEncoder().encode('file contents here')
397
+ * };
398
+ */
74
399
  export interface PackableObject {
400
+ /** Object type as a string ('blob', 'tree', 'commit', or 'tag') */
75
401
  type: 'blob' | 'tree' | 'commit' | 'tag';
402
+ /** The raw object data (will be compressed during packing) */
76
403
  data: Uint8Array;
77
404
  }
78
405
  /**
79
- * Create a packfile from a list of objects
80
- * @param objects - Array of objects to pack
81
- * @returns Complete packfile as Uint8Array
406
+ * Creates a complete packfile from an array of objects.
407
+ *
408
+ * @description Generates a valid Git packfile containing the specified objects.
409
+ * The resulting packfile includes:
410
+ * - 12-byte header (signature, version, object count)
411
+ * - Each object (header + zlib-compressed data)
412
+ * - 20-byte SHA-1 checksum trailer
413
+ *
414
+ * **Process:**
415
+ * 1. Creates the pack header with signature "PACK", version 2, and object count
416
+ * 2. For each object, encodes type/size header and compresses data with zlib
417
+ * 3. Appends SHA-1 checksum of the entire pack content
418
+ *
419
+ * **Important Notes:**
420
+ * - Objects are packed in the order provided (no reordering for delta compression)
421
+ * - This function creates full objects only (no delta compression)
422
+ * - For delta compression, use the generation module functions
423
+ *
424
+ * @param {PackableObject[]} objects - Array of objects to include in the packfile
425
+ * @returns {Uint8Array} Complete packfile as binary data
426
+ *
427
+ * @example
428
+ * // Create a packfile with a single blob
429
+ * const objects: PackableObject[] = [
430
+ * { type: 'blob', data: new TextEncoder().encode('Hello, World!') }
431
+ * ];
432
+ * const packfile = createPackfile(objects);
433
+ * // Write packfile to disk or send over network
434
+ *
435
+ * @example
436
+ * // Create a packfile with multiple objects
437
+ * const objects: PackableObject[] = [
438
+ * { type: 'blob', data: fileContent1 },
439
+ * { type: 'blob', data: fileContent2 },
440
+ * { type: 'tree', data: treeData },
441
+ * { type: 'commit', data: commitData }
442
+ * ];
443
+ * const packfile = createPackfile(objects);
82
444
  */
83
445
  export declare function createPackfile(objects: PackableObject[]): Uint8Array;
84
446
  //# sourceMappingURL=format.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/pack/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,eAAO,MAAM,cAAc,SAAS,CAAA;AACpC,eAAO,MAAM,YAAY,IAAI,CAAA;AAG7B,oBAAY,cAAc;IACxB,UAAU,IAAI;IACd,QAAQ,IAAI;IACZ,QAAQ,IAAI;IACZ,OAAO,IAAI;IACX,aAAa,IAAI;IACjB,aAAa,IAAI;CAClB;AAGD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAiBnE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAalE;AAGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CActD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CA2BnG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAuBhF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG;IACnE,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;CAClB,CAyCA;AAGD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAqB5D;AAGD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAQlF;AAGD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;IACxC,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,UAAU,CA2DpE"}
1
+ {"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/pack/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAKH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,SAAS,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B;;;;;;;;;;;;;;;;;GAiBG;AACH,oBAAY,cAAc;IACxB,qFAAqF;IACrF,UAAU,IAAI;IACd,uDAAuD;IACvD,QAAQ,IAAI;IACZ,4CAA4C;IAC5C,QAAQ,IAAI;IACZ,8BAA8B;IAC9B,OAAO,IAAI;IACX,kFAAkF;IAClF,aAAa,IAAI;IACjB,mEAAmE;IACnE,aAAa,IAAI;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAiBnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAalE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CActD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CA2BnG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAuBhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG;IACnE,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;CAClB,CAyCA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAqB5D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,IAAI,EAAE,cAAc,CAAA;IACpB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAQlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;IACxC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,UAAU,CA2DpE"}