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,118 +1,441 @@
1
1
  /**
2
- * Git Packfile Generation
3
- *
4
- * This module provides packfile generation capabilities including:
5
- * - Pack generation from object sets
6
- * - Delta compression (OFS_DELTA, REF_DELTA)
7
- * - Proper PACK header with signature, version, object count
8
- * - SHA-1 checksum at end of pack
9
- * - Variable-length integer encoding for sizes
2
+ * @fileoverview Git Packfile Generation
3
+ *
4
+ * This module provides comprehensive packfile generation capabilities for creating
5
+ * Git packfiles programmatically. It supports both full object storage and delta
6
+ * compression for efficient packing.
7
+ *
8
+ * ## Features
9
+ *
10
+ * - **Full Object Packing**: Store objects without delta compression
11
+ * - **Delta Compression**: Automatic OFS_DELTA generation for similar objects
12
+ * - **REF_DELTA Support**: Reference-based deltas for thin packs
13
+ * - **Configurable Options**: Control delta depth, window size, compression level
14
+ * - **Thin Pack Generation**: Create packs that reference external objects
15
+ *
16
+ * ## Pack Structure
17
+ *
18
+ * Generated packfiles follow the Git packfile v2 format:
19
+ * - 12-byte header (signature + version + object count)
20
+ * - Sequence of packed objects (header + compressed data)
21
+ * - 20-byte SHA-1 trailer
22
+ *
23
+ * ## Delta Compression
24
+ *
25
+ * When enabled, the generator uses a sliding window approach to find similar
26
+ * objects and create delta chains. OFS_DELTA is preferred as it's more efficient
27
+ * than REF_DELTA for local storage.
28
+ *
29
+ * @module pack/generation
30
+ * @see {@link https://git-scm.com/docs/pack-format} Git Pack Format Documentation
31
+ *
32
+ * @example
33
+ * // Simple packfile generation
34
+ * import { generatePackfile, PackableObject, PackObjectType } from './generation';
35
+ *
36
+ * const objects: PackableObject[] = [
37
+ * { sha: 'abc123...', type: PackObjectType.OBJ_BLOB, data: blobData }
38
+ * ];
39
+ * const packfile = generatePackfile(objects);
40
+ *
41
+ * @example
42
+ * // Using PackfileGenerator with options
43
+ * import { PackfileGenerator, PackObjectType } from './generation';
44
+ *
45
+ * const generator = new PackfileGenerator({
46
+ * enableDeltaCompression: true,
47
+ * maxDeltaDepth: 50,
48
+ * windowSize: 10
49
+ * });
50
+ *
51
+ * generator.addObject({ sha: '...', type: PackObjectType.OBJ_BLOB, data: ... });
52
+ * const result = generator.generate();
10
53
  */
11
54
  import { PackObjectType } from './format';
12
55
  /**
13
- * An object that can be packed
56
+ * Represents an object that can be packed into a packfile.
57
+ *
58
+ * @description Contains all the information needed to add an object to a pack:
59
+ * the object's SHA-1 identifier, its type, raw data, and optional path for
60
+ * delta base selection optimization.
61
+ *
62
+ * @interface PackableObject
63
+ *
64
+ * @example
65
+ * const blob: PackableObject = {
66
+ * sha: 'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3',
67
+ * type: PackObjectType.OBJ_BLOB,
68
+ * data: new TextEncoder().encode('Hello, World!'),
69
+ * path: 'README.md' // Optional: helps with delta base selection
70
+ * };
14
71
  */
15
72
  export interface PackableObject {
73
+ /** The 40-character hexadecimal SHA-1 hash of the object */
16
74
  sha: string;
75
+ /** The Git object type (commit, tree, blob, or tag) */
17
76
  type: PackObjectType;
77
+ /** The raw (uncompressed) object data */
18
78
  data: Uint8Array;
79
+ /** Optional file path, used to improve delta base selection */
19
80
  path?: string;
20
81
  }
21
82
  /**
22
- * A delta object that references an external base
83
+ * Represents a delta object that references an external base.
84
+ *
85
+ * @description Used for REF_DELTA objects in thin packs where the base
86
+ * object is not included in the packfile. The receiver must have the base
87
+ * object available to reconstruct the target.
88
+ *
89
+ * @interface DeltaObject
23
90
  */
24
91
  export interface DeltaObject {
92
+ /** SHA-1 of the delta object itself */
25
93
  sha: string;
94
+ /** The original object type (before delta encoding) */
26
95
  type: PackObjectType;
96
+ /** SHA-1 of the base object this delta references */
27
97
  baseSha: string;
98
+ /** The delta data (instructions to transform base to target) */
28
99
  delta: Uint8Array;
29
100
  }
30
101
  /**
31
- * Options for pack generation
102
+ * Configuration options for the PackfileGenerator.
103
+ *
104
+ * @description Controls how objects are packed, including delta compression
105
+ * settings, compression level, and minimum object sizes for delta consideration.
106
+ *
107
+ * @interface GeneratorOptions
108
+ *
109
+ * @example
110
+ * const options: GeneratorOptions = {
111
+ * enableDeltaCompression: true,
112
+ * maxDeltaDepth: 50,
113
+ * windowSize: 10,
114
+ * compressionLevel: 6
115
+ * };
32
116
  */
33
117
  export interface GeneratorOptions {
118
+ /** Enable delta compression (default: false) */
34
119
  enableDeltaCompression?: boolean;
120
+ /** Maximum depth of delta chains (default: 50) */
35
121
  maxDeltaDepth?: number;
122
+ /** Number of objects to consider as delta bases (default: 10) */
36
123
  windowSize?: number;
124
+ /** Zlib compression level 0-9 (default: 6) */
37
125
  compressionLevel?: number;
126
+ /** Use REF_DELTA instead of OFS_DELTA (default: false) */
38
127
  useRefDelta?: boolean;
128
+ /** Minimum object size to consider for delta compression (default: 0) */
39
129
  minDeltaSize?: number;
40
130
  }
41
131
  /**
42
- * Statistics from pack generation
132
+ * Statistics collected during pack generation.
133
+ *
134
+ * @description Provides metrics about the generated packfile including
135
+ * object counts, sizes, compression ratios, and timing information.
136
+ *
137
+ * @interface PackGenerationStats
43
138
  */
44
139
  export interface PackGenerationStats {
140
+ /** Total number of objects in the packfile */
45
141
  totalObjects: number;
142
+ /** Number of objects stored as deltas */
46
143
  deltaObjects: number;
144
+ /** Total uncompressed size of all objects in bytes */
47
145
  totalSize: number;
146
+ /** Total compressed size of all object data in bytes */
48
147
  compressedSize: number;
148
+ /** Maximum delta chain depth achieved */
49
149
  maxDeltaDepth: number;
150
+ /** Time taken to generate the packfile in milliseconds */
50
151
  generationTimeMs: number;
51
152
  }
52
153
  /**
53
- * Result of pack generation
154
+ * Result returned by PackfileGenerator.generate().
155
+ *
156
+ * @description Contains the generated packfile data (without trailing checksum),
157
+ * the computed checksum, and generation statistics. To create a complete packfile,
158
+ * concatenate packData with checksum.
159
+ *
160
+ * @interface GeneratedPackfile
161
+ *
162
+ * @example
163
+ * const result = generator.generate();
164
+ * // Create complete packfile
165
+ * const complete = new Uint8Array(result.packData.length + 20);
166
+ * complete.set(result.packData, 0);
167
+ * complete.set(result.checksum, result.packData.length);
54
168
  */
55
169
  export interface GeneratedPackfile {
170
+ /** Packfile data (header + objects, without trailing checksum) */
56
171
  packData: Uint8Array;
172
+ /** SHA-1 checksum of packData */
57
173
  checksum: Uint8Array;
174
+ /** Statistics from the generation process */
58
175
  stats: PackGenerationStats;
59
176
  }
60
177
  /**
61
- * A candidate for delta base selection
178
+ * Represents a candidate for delta base selection.
179
+ *
180
+ * @description Contains the essential information about an object that could
181
+ * serve as a delta base. Used by the thin pack generator to evaluate
182
+ * potential base objects for delta compression.
183
+ *
184
+ * @interface DeltaCandidate
62
185
  */
63
186
  export interface DeltaCandidate {
187
+ /** SHA-1 of the candidate base object */
64
188
  sha: string;
189
+ /** Object type (must match target for delta consideration) */
65
190
  type: PackObjectType;
191
+ /** Raw object data (used to compute delta) */
66
192
  data: Uint8Array;
67
193
  }
68
194
  /**
69
- * Options for thin pack generation
195
+ * Options for thin pack generation.
196
+ *
197
+ * @description Thin packs contain REF_DELTA objects that reference base objects
198
+ * not included in the pack. This is used for network transfers where the receiver
199
+ * is expected to already have the base objects.
200
+ *
201
+ * @interface ThinPackOptions
70
202
  */
71
203
  export interface ThinPackOptions {
204
+ /** Set of SHA-1 hashes of objects the receiver already has */
72
205
  externalObjects: Set<string>;
206
+ /** Optional map of SHA to data for external objects (for computing deltas) */
73
207
  baseData?: Map<string, Uint8Array>;
74
208
  }
75
209
  /**
76
- * Result of thin pack generation
210
+ * Result of thin pack generation.
211
+ *
212
+ * @description Contains the generated thin pack along with metadata about
213
+ * its structure and any missing base objects.
214
+ *
215
+ * @interface ThinPackResult
77
216
  */
78
217
  export interface ThinPackResult {
218
+ /** The generated packfile data (without trailing checksum) */
79
219
  packData: Uint8Array;
220
+ /** SHA-1 checksum of the pack data */
80
221
  checksum: Uint8Array;
222
+ /** Whether the pack contains REF_DELTA objects referencing external bases */
81
223
  isThin: boolean;
224
+ /** List of base SHA-1s that are referenced but not included */
82
225
  missingBases: string[];
226
+ /** Generation statistics */
83
227
  stats: PackGenerationStats;
84
228
  }
85
229
  /**
86
- * Compute SHA-1 checksum of pack content
230
+ * Computes the SHA-1 checksum of pack content.
231
+ *
232
+ * @description Calculates the 20-byte SHA-1 hash that serves as the pack's
233
+ * checksum/trailer. This checksum is appended to the pack and also used
234
+ * in the corresponding .idx file.
235
+ *
236
+ * @param {Uint8Array} data - The pack data to checksum
237
+ * @returns {Uint8Array} 20-byte SHA-1 checksum
238
+ *
239
+ * @example
240
+ * const packWithoutChecksum = generatePackContent(objects);
241
+ * const checksum = computePackChecksum(packWithoutChecksum);
242
+ * // Append checksum to create complete packfile
87
243
  */
88
244
  export declare function computePackChecksum(data: Uint8Array): Uint8Array;
89
245
  /**
90
- * Order objects for optimal compression
91
- * Groups by type, then sorts by size (larger first for better delta bases)
246
+ * Orders objects for optimal delta compression.
247
+ *
248
+ * @description Sorts objects to maximize delta compression efficiency by:
249
+ * 1. Grouping by type (commits, trees, blobs, tags)
250
+ * 2. Within each type, grouping by path (similar files together)
251
+ * 3. Within path groups, sorting by size (larger first as better bases)
252
+ *
253
+ * This ordering ensures that similar objects are adjacent, improving the
254
+ * chances of finding good delta bases within the sliding window.
255
+ *
256
+ * @param {PackableObject[]} objects - Objects to order
257
+ * @returns {PackableObject[]} New array with objects in optimal order
258
+ *
259
+ * @example
260
+ * const ordered = orderObjectsForCompression(objects);
261
+ * // Use ordered array for pack generation
92
262
  */
93
263
  export declare function orderObjectsForCompression(objects: PackableObject[]): PackableObject[];
94
264
  /**
95
- * Select the best delta base from candidates
265
+ * Selects the best delta base from a set of candidates.
266
+ *
267
+ * @description Evaluates each candidate by computing similarity with the target
268
+ * and returns the most similar object if it exceeds the threshold.
269
+ *
270
+ * **Selection Criteria:**
271
+ * - Must be same type as target
272
+ * - Must not be the target itself
273
+ * - Similarity must exceed 30% threshold
274
+ *
275
+ * @param {DeltaCandidate} target - The object to find a base for
276
+ * @param {DeltaCandidate[]} candidates - Potential base objects
277
+ * @returns {DeltaCandidate | null} Best candidate or null if none suitable
278
+ *
279
+ * @example
280
+ * const base = selectDeltaBase(targetObj, windowObjects);
281
+ * if (base) {
282
+ * const delta = createDelta(base.data, targetObj.data);
283
+ * }
96
284
  */
97
285
  export declare function selectDeltaBase(target: DeltaCandidate, candidates: DeltaCandidate[]): DeltaCandidate | null;
286
+ /**
287
+ * Generator class for creating Git packfiles.
288
+ *
289
+ * @description Provides a fluent API for building packfiles with support for:
290
+ * - Adding objects incrementally
291
+ * - Optional delta compression with configurable parameters
292
+ * - Both OFS_DELTA and REF_DELTA encoding
293
+ * - Statistics collection during generation
294
+ *
295
+ * **Usage Pattern:**
296
+ * 1. Create generator with desired options
297
+ * 2. Add objects using addObject() or addDeltaObject()
298
+ * 3. Call generate() to produce the packfile
299
+ * 4. Optionally call reset() to reuse the generator
300
+ *
301
+ * @class PackfileGenerator
302
+ *
303
+ * @example
304
+ * // Basic usage
305
+ * const generator = new PackfileGenerator();
306
+ * generator.addObject({ sha: '...', type: PackObjectType.OBJ_BLOB, data: ... });
307
+ * generator.addObject({ sha: '...', type: PackObjectType.OBJ_TREE, data: ... });
308
+ * const result = generator.generate();
309
+ *
310
+ * @example
311
+ * // With delta compression
312
+ * const generator = new PackfileGenerator({
313
+ * enableDeltaCompression: true,
314
+ * maxDeltaDepth: 50,
315
+ * windowSize: 10
316
+ * });
317
+ *
318
+ * for (const obj of objects) {
319
+ * generator.addObject(obj);
320
+ * }
321
+ *
322
+ * const { packData, checksum, stats } = generator.generate();
323
+ * console.log(`Compressed ${stats.deltaObjects} objects as deltas`);
324
+ */
98
325
  export declare class PackfileGenerator {
99
326
  private objects;
100
327
  private deltaObjects;
101
328
  private options;
329
+ /**
330
+ * Creates a new PackfileGenerator with the specified options.
331
+ *
332
+ * @param {GeneratorOptions} [options={}] - Configuration options
333
+ */
102
334
  constructor(options?: GeneratorOptions);
335
+ /**
336
+ * Gets the total number of objects added to the generator.
337
+ * @returns {number} Count of regular objects plus delta objects
338
+ */
103
339
  get objectCount(): number;
340
+ /**
341
+ * Adds an object to be included in the packfile.
342
+ *
343
+ * @description Objects are deduplicated by SHA. If an object with the same SHA
344
+ * has already been added, this call is a no-op.
345
+ *
346
+ * @param {PackableObject} object - The object to add
347
+ */
104
348
  addObject(object: PackableObject): void;
349
+ /**
350
+ * Adds a pre-computed delta object for thin pack generation.
351
+ *
352
+ * @description Use this for REF_DELTA objects that reference external bases.
353
+ * The delta must already be computed.
354
+ *
355
+ * @param {DeltaObject} deltaObj - The delta object to add
356
+ */
105
357
  addDeltaObject(deltaObj: DeltaObject): void;
358
+ /**
359
+ * Resets the generator to its initial state.
360
+ *
361
+ * @description Clears all added objects and delta objects, allowing the
362
+ * generator to be reused for a new packfile.
363
+ */
106
364
  reset(): void;
365
+ /**
366
+ * Generates the packfile from all added objects.
367
+ *
368
+ * @description Produces a complete packfile including:
369
+ * - 12-byte header
370
+ * - All objects (with optional delta compression)
371
+ * - Generation statistics
372
+ *
373
+ * Note: The returned packData does NOT include the trailing checksum.
374
+ * Concatenate packData with checksum to create the complete packfile.
375
+ *
376
+ * @returns {GeneratedPackfile} Pack data, checksum, and statistics
377
+ *
378
+ * @example
379
+ * const result = generator.generate();
380
+ * // Write complete packfile
381
+ * const complete = new Uint8Array(result.packData.length + 20);
382
+ * complete.set(result.packData);
383
+ * complete.set(result.checksum, result.packData.length);
384
+ */
107
385
  generate(): GeneratedPackfile;
108
386
  }
109
387
  /**
110
- * Generate a packfile from an array of objects
111
- * Returns a complete packfile with trailing SHA-1 checksum
388
+ * Generates a complete packfile from an array of objects.
389
+ *
390
+ * @description Convenience function that creates a PackfileGenerator, adds all
391
+ * objects, generates the pack, and returns a complete packfile with the trailing
392
+ * SHA-1 checksum appended.
393
+ *
394
+ * This function does not use delta compression. For delta compression, use
395
+ * the PackfileGenerator class directly with enableDeltaCompression option.
396
+ *
397
+ * @param {PackableObject[]} objects - Array of objects to pack
398
+ * @returns {Uint8Array} Complete packfile with header, objects, and checksum
399
+ *
400
+ * @example
401
+ * const objects: PackableObject[] = [
402
+ * { sha: 'abc...', type: PackObjectType.OBJ_BLOB, data: blobData },
403
+ * { sha: 'def...', type: PackObjectType.OBJ_TREE, data: treeData },
404
+ * { sha: 'ghi...', type: PackObjectType.OBJ_COMMIT, data: commitData }
405
+ * ];
406
+ *
407
+ * const packfile = generatePackfile(objects);
408
+ * await fs.writeFile('pack-abc123.pack', packfile);
112
409
  */
113
410
  export declare function generatePackfile(objects: PackableObject[]): Uint8Array;
114
411
  /**
115
- * Generate a thin pack that can reference external objects
412
+ * Generates a thin pack that can reference external base objects.
413
+ *
414
+ * @description Creates a packfile where objects can be stored as REF_DELTA
415
+ * referencing base objects not included in the pack. This is typically used
416
+ * for network transfers where the receiver already has some objects.
417
+ *
418
+ * **Thin Pack Behavior:**
419
+ * - Attempts to delta-compress objects against external bases
420
+ * - Uses REF_DELTA format (base referenced by SHA-1)
421
+ * - Falls back to full objects when delta is not beneficial
422
+ * - Tracks which external bases are referenced
423
+ *
424
+ * @param {PackableObject[]} objects - Array of objects to pack
425
+ * @param {ThinPackOptions} options - Configuration including external object set
426
+ * @returns {ThinPackResult} Pack data, checksum, and metadata about external refs
427
+ *
428
+ * @example
429
+ * // Generate thin pack for git push
430
+ * const externalObjects = new Set(['abc123...', 'def456...']); // Objects server has
431
+ * const baseData = new Map([['abc123...', baseObjData]]); // Data for delta computation
432
+ *
433
+ * const result = generateThinPack(objectsToSend, {
434
+ * externalObjects,
435
+ * baseData
436
+ * });
437
+ *
438
+ * console.log(`Created thin pack with ${result.missingBases.length} external refs`);
116
439
  */
117
440
  export declare function generateThinPack(objects: PackableObject[], options: ThinPackOptions): ThinPackResult;
118
441
  //# sourceMappingURL=generation.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../../src/pack/generation.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../../src/pack/generation.ts"],"names":[],"mappings":"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"}