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,37 +1,172 @@
1
1
  /**
2
- * ObjectStore - Git object storage implementation
2
+ * @fileoverview Git Object Store for Durable Objects
3
3
  *
4
- * Handles CRUD operations for git objects (blob, tree, commit, tag)
5
- * with SHA-1 hash computation and proper git object format.
4
+ * This module provides a Git object storage implementation backed by SQLite
5
+ * within Cloudflare Durable Objects. It handles CRUD operations for all four
6
+ * Git object types (blob, tree, commit, tag) with proper SHA-1 hash computation.
7
+ *
8
+ * **Key Features**:
9
+ * - Content-addressable storage using SHA-1 hashes
10
+ * - Write-ahead logging (WAL) for durability
11
+ * - Object index for tiered storage support
12
+ * - Batch operations for efficiency
13
+ * - Typed accessors for each Git object type
14
+ *
15
+ * @module durable-object/object-store
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * import { ObjectStore } from './durable-object/object-store'
20
+ *
21
+ * const store = new ObjectStore(durableObjectStorage)
22
+ *
23
+ * // Store a blob
24
+ * const content = new TextEncoder().encode('Hello, World!')
25
+ * const sha = await store.putObject('blob', content)
26
+ *
27
+ * // Retrieve it
28
+ * const obj = await store.getObject(sha)
29
+ * console.log(obj?.type, obj?.size)
30
+ *
31
+ * // Get typed object
32
+ * const blob = await store.getBlobObject(sha)
33
+ * ```
6
34
  */
7
35
  import { DurableObjectStorage } from './schema';
8
36
  import { ObjectType, BlobObject, TreeObject, CommitObject, TagObject, TreeEntry, Author } from '../types/objects';
9
37
  /**
10
- * Stored object record in SQLite
38
+ * Stored object record as persisted in SQLite.
39
+ *
40
+ * @description
41
+ * Represents a Git object with metadata as stored in the database.
42
+ * The `data` field contains the object content WITHOUT the Git header.
43
+ *
44
+ * @example
45
+ * ```typescript
46
+ * const obj: StoredObject = {
47
+ * sha: 'abc123...',
48
+ * type: 'blob',
49
+ * size: 13,
50
+ * data: new Uint8Array([...]),
51
+ * createdAt: 1704067200000
52
+ * }
53
+ * ```
11
54
  */
12
55
  export interface StoredObject {
56
+ /** 40-character SHA-1 hash (primary key) */
13
57
  sha: string;
58
+ /** Object type: 'blob', 'tree', 'commit', or 'tag' */
14
59
  type: ObjectType;
60
+ /** Size of the data in bytes */
15
61
  size: number;
62
+ /** Raw object content (without Git header) */
16
63
  data: Uint8Array;
64
+ /** Unix timestamp (milliseconds) when object was created */
17
65
  createdAt: number;
18
66
  }
19
67
  /**
20
- * ObjectStore class for managing git objects in SQLite storage
68
+ * ObjectStore class for managing Git objects in SQLite storage.
69
+ *
70
+ * @description
71
+ * Provides a complete implementation of Git object storage operations.
72
+ * All objects are stored in the `objects` table and indexed in `object_index`
73
+ * for tiered storage support. Write operations are logged to WAL for durability.
74
+ *
75
+ * @example
76
+ * ```typescript
77
+ * const store = new ObjectStore(durableObjectStorage)
78
+ *
79
+ * // Create a commit
80
+ * const commitSha = await store.putCommitObject({
81
+ * tree: treeSha,
82
+ * parents: [parentSha],
83
+ * author: { name: 'Alice', email: 'alice@example.com', timestamp: 1704067200, timezone: '+0000' },
84
+ * committer: { name: 'Alice', email: 'alice@example.com', timestamp: 1704067200, timezone: '+0000' },
85
+ * message: 'Initial commit'
86
+ * })
87
+ *
88
+ * // Read it back
89
+ * const commit = await store.getCommitObject(commitSha)
90
+ * console.log(commit?.message)
91
+ * ```
21
92
  */
22
93
  export declare class ObjectStore {
23
94
  private storage;
95
+ /**
96
+ * Create a new ObjectStore.
97
+ *
98
+ * @param storage - Durable Object storage interface with SQL support
99
+ */
24
100
  constructor(storage: DurableObjectStorage);
25
101
  /**
26
- * Store a raw object and return its SHA
102
+ * Store a raw object and return its SHA.
103
+ *
104
+ * @description
105
+ * Computes the SHA-1 hash of the object in Git format (type + size + content),
106
+ * logs the operation to WAL, stores the object, and updates the object index.
107
+ * If an object with the same SHA already exists, it is replaced (idempotent).
108
+ *
109
+ * @param type - Object type ('blob', 'tree', 'commit', 'tag')
110
+ * @param data - Raw object content (without Git header)
111
+ * @returns 40-character SHA-1 hash of the stored object
112
+ *
113
+ * @example
114
+ * ```typescript
115
+ * const content = new TextEncoder().encode('file content')
116
+ * const sha = await store.putObject('blob', content)
117
+ * console.log(`Stored blob: ${sha}`)
118
+ * ```
27
119
  */
28
120
  putObject(type: ObjectType, data: Uint8Array): Promise<string>;
29
121
  /**
30
- * Store a tree object with entries
122
+ * Store a tree object with entries.
123
+ *
124
+ * @description
125
+ * Creates a Git tree object from an array of entries. Entries are sorted
126
+ * by name (with directories treated as having trailing slashes for sorting).
127
+ * Each entry is serialized as: "{mode} {name}\0{20-byte-sha}"
128
+ *
129
+ * @param entries - Array of tree entries (files and subdirectories)
130
+ * @returns 40-character SHA-1 hash of the stored tree
131
+ *
132
+ * @example
133
+ * ```typescript
134
+ * const treeSha = await store.putTreeObject([
135
+ * { mode: '100644', name: 'README.md', sha: blobSha },
136
+ * { mode: '040000', name: 'src', sha: subdirSha }
137
+ * ])
138
+ * ```
31
139
  */
32
140
  putTreeObject(entries: TreeEntry[]): Promise<string>;
33
141
  /**
34
- * Store a commit object
142
+ * Store a commit object.
143
+ *
144
+ * @description
145
+ * Creates a Git commit object with the specified tree, parents, author,
146
+ * committer, and message. The commit content is formatted according to
147
+ * the Git commit format specification.
148
+ *
149
+ * @param commit - Commit data
150
+ * @param commit.tree - SHA of the root tree object
151
+ * @param commit.parents - Array of parent commit SHAs (empty for root commit)
152
+ * @param commit.author - Author information
153
+ * @param commit.committer - Committer information
154
+ * @param commit.message - Commit message
155
+ * @returns 40-character SHA-1 hash of the stored commit
156
+ *
157
+ * @example
158
+ * ```typescript
159
+ * const now = Math.floor(Date.now() / 1000)
160
+ * const author = { name: 'Alice', email: 'alice@example.com', timestamp: now, timezone: '+0000' }
161
+ *
162
+ * const sha = await store.putCommitObject({
163
+ * tree: treeSha,
164
+ * parents: [],
165
+ * author,
166
+ * committer: author,
167
+ * message: 'Initial commit\n\nThis is the first commit.'
168
+ * })
169
+ * ```
35
170
  */
36
171
  putCommitObject(commit: {
37
172
  tree: string;
@@ -41,7 +176,34 @@ export declare class ObjectStore {
41
176
  message: string;
42
177
  }): Promise<string>;
43
178
  /**
44
- * Store a tag object
179
+ * Store a tag object (annotated tag).
180
+ *
181
+ * @description
182
+ * Creates a Git tag object pointing to another object with tagger
183
+ * information and a message. The tag content is formatted according
184
+ * to the Git tag format specification.
185
+ *
186
+ * @param tag - Tag data
187
+ * @param tag.object - SHA of the object being tagged
188
+ * @param tag.objectType - Type of the object being tagged
189
+ * @param tag.tagger - Tagger information
190
+ * @param tag.message - Tag message
191
+ * @param tag.name - Tag name
192
+ * @returns 40-character SHA-1 hash of the stored tag object
193
+ *
194
+ * @example
195
+ * ```typescript
196
+ * const now = Math.floor(Date.now() / 1000)
197
+ * const tagger = { name: 'Bob', email: 'bob@example.com', timestamp: now, timezone: '+0000' }
198
+ *
199
+ * const sha = await store.putTagObject({
200
+ * object: commitSha,
201
+ * objectType: 'commit',
202
+ * tagger,
203
+ * message: 'Release v1.0.0',
204
+ * name: 'v1.0.0'
205
+ * })
206
+ * ```
45
207
  */
46
208
  putTagObject(tag: {
47
209
  object: string;
@@ -51,62 +213,278 @@ export declare class ObjectStore {
51
213
  name: string;
52
214
  }): Promise<string>;
53
215
  /**
54
- * Retrieve an object by SHA
216
+ * Retrieve an object by SHA.
217
+ *
218
+ * @description
219
+ * Fetches an object from the database by its SHA-1 hash.
220
+ * Returns null if the object doesn't exist or if the SHA is invalid.
221
+ *
222
+ * @param sha - 40-character SHA-1 hash
223
+ * @returns The stored object or null if not found
224
+ *
225
+ * @example
226
+ * ```typescript
227
+ * const obj = await store.getObject(sha)
228
+ * if (obj) {
229
+ * console.log(`Found ${obj.type} of ${obj.size} bytes`)
230
+ * }
231
+ * ```
55
232
  */
56
233
  getObject(sha: string): Promise<StoredObject | null>;
57
234
  /**
58
- * Delete an object by SHA
235
+ * Delete an object by SHA.
236
+ *
237
+ * @description
238
+ * Removes an object from both the objects table and the object index.
239
+ * The operation is logged to WAL. Returns false if the object doesn't exist.
240
+ *
241
+ * **Warning**: Deleting objects that are still referenced by other objects
242
+ * (e.g., blobs referenced by trees) will corrupt the repository.
243
+ *
244
+ * @param sha - 40-character SHA-1 hash
245
+ * @returns True if the object was deleted, false if it didn't exist
246
+ *
247
+ * @example
248
+ * ```typescript
249
+ * const deleted = await store.deleteObject(sha)
250
+ * if (deleted) {
251
+ * console.log('Object removed')
252
+ * }
253
+ * ```
59
254
  */
60
255
  deleteObject(sha: string): Promise<boolean>;
61
256
  /**
62
- * Check if an object exists
257
+ * Check if an object exists.
258
+ *
259
+ * @description
260
+ * Efficiently checks for object existence without fetching the full content.
261
+ *
262
+ * @param sha - 40-character SHA-1 hash
263
+ * @returns True if the object exists, false otherwise
264
+ *
265
+ * @example
266
+ * ```typescript
267
+ * if (await store.hasObject(sha)) {
268
+ * console.log('Object exists')
269
+ * }
270
+ * ```
63
271
  */
64
272
  hasObject(sha: string): Promise<boolean>;
65
273
  /**
66
- * Verify an object's integrity by recomputing its hash
274
+ * Verify an object's integrity by recomputing its hash.
275
+ *
276
+ * @description
277
+ * Computes the SHA-1 hash of the stored object and compares it
278
+ * to the stored SHA. Returns false if the object is corrupted
279
+ * or doesn't exist.
280
+ *
281
+ * @param sha - 40-character SHA-1 hash to verify
282
+ * @returns True if the computed hash matches, false otherwise
283
+ *
284
+ * @example
285
+ * ```typescript
286
+ * if (await store.verifyObject(sha)) {
287
+ * console.log('Object integrity verified')
288
+ * } else {
289
+ * console.log('Object is corrupted or missing')
290
+ * }
291
+ * ```
67
292
  */
68
293
  verifyObject(sha: string): Promise<boolean>;
69
294
  /**
70
- * Get object type by SHA
295
+ * Get object type by SHA.
296
+ *
297
+ * @description
298
+ * Returns just the type of an object without fetching its content.
299
+ *
300
+ * @param sha - 40-character SHA-1 hash
301
+ * @returns Object type or null if not found
302
+ *
303
+ * @example
304
+ * ```typescript
305
+ * const type = await store.getObjectType(sha)
306
+ * if (type === 'commit') {
307
+ * // Handle commit
308
+ * }
309
+ * ```
71
310
  */
72
311
  getObjectType(sha: string): Promise<ObjectType | null>;
73
312
  /**
74
- * Get object size by SHA
313
+ * Get object size by SHA.
314
+ *
315
+ * @description
316
+ * Returns just the size of an object without fetching its content.
317
+ *
318
+ * @param sha - 40-character SHA-1 hash
319
+ * @returns Object size in bytes or null if not found
320
+ *
321
+ * @example
322
+ * ```typescript
323
+ * const size = await store.getObjectSize(sha)
324
+ * console.log(`Object is ${size} bytes`)
325
+ * ```
75
326
  */
76
327
  getObjectSize(sha: string): Promise<number | null>;
77
328
  /**
78
- * Store multiple objects in a batch
329
+ * Store multiple objects in a batch.
330
+ *
331
+ * @description
332
+ * Stores multiple objects sequentially. Each object is stored
333
+ * individually with its own WAL entry. For atomic batch operations,
334
+ * consider wrapping in a transaction.
335
+ *
336
+ * @param objects - Array of objects to store
337
+ * @returns Array of SHA-1 hashes in the same order as input
338
+ *
339
+ * @example
340
+ * ```typescript
341
+ * const shas = await store.putObjects([
342
+ * { type: 'blob', data: content1 },
343
+ * { type: 'blob', data: content2 }
344
+ * ])
345
+ * ```
79
346
  */
80
347
  putObjects(objects: {
81
348
  type: ObjectType;
82
349
  data: Uint8Array;
83
350
  }[]): Promise<string[]>;
84
351
  /**
85
- * Retrieve multiple objects by SHA
352
+ * Retrieve multiple objects by SHA.
353
+ *
354
+ * @description
355
+ * Fetches multiple objects by their SHAs. Missing objects
356
+ * are returned as null in the result array.
357
+ *
358
+ * @param shas - Array of 40-character SHA-1 hashes
359
+ * @returns Array of objects (or null for missing) in the same order
360
+ *
361
+ * @example
362
+ * ```typescript
363
+ * const objects = await store.getObjects([sha1, sha2, sha3])
364
+ * objects.forEach((obj, i) => {
365
+ * if (obj) {
366
+ * console.log(`${i}: ${obj.type}`)
367
+ * }
368
+ * })
369
+ * ```
86
370
  */
87
371
  getObjects(shas: string[]): Promise<(StoredObject | null)[]>;
88
372
  /**
89
- * Get a blob object with parsed content
373
+ * Get a blob object with typed result.
374
+ *
375
+ * @description
376
+ * Fetches an object and returns it as a BlobObject if it's a blob.
377
+ * Returns null if the object doesn't exist or isn't a blob.
378
+ *
379
+ * @param sha - 40-character SHA-1 hash
380
+ * @returns Typed BlobObject or null
381
+ *
382
+ * @example
383
+ * ```typescript
384
+ * const blob = await store.getBlobObject(sha)
385
+ * if (blob) {
386
+ * const content = new TextDecoder().decode(blob.data)
387
+ * console.log(content)
388
+ * }
389
+ * ```
90
390
  */
91
391
  getBlobObject(sha: string): Promise<BlobObject | null>;
92
392
  /**
93
- * Get a tree object with parsed entries
393
+ * Get a tree object with parsed entries.
394
+ *
395
+ * @description
396
+ * Fetches and parses a tree object, extracting all entries
397
+ * with their modes, names, and SHA references.
398
+ *
399
+ * @param sha - 40-character SHA-1 hash
400
+ * @returns Parsed TreeObject with entries or null
401
+ *
402
+ * @example
403
+ * ```typescript
404
+ * const tree = await store.getTreeObject(sha)
405
+ * if (tree) {
406
+ * for (const entry of tree.entries) {
407
+ * console.log(`${entry.mode} ${entry.name} ${entry.sha}`)
408
+ * }
409
+ * }
410
+ * ```
94
411
  */
95
412
  getTreeObject(sha: string): Promise<TreeObject | null>;
96
413
  /**
97
- * Get a commit object with parsed fields
414
+ * Get a commit object with parsed fields.
415
+ *
416
+ * @description
417
+ * Fetches and parses a commit object, extracting tree SHA,
418
+ * parent SHAs, author, committer, and message.
419
+ *
420
+ * @param sha - 40-character SHA-1 hash
421
+ * @returns Parsed CommitObject or null
422
+ *
423
+ * @example
424
+ * ```typescript
425
+ * const commit = await store.getCommitObject(sha)
426
+ * if (commit) {
427
+ * console.log(`Author: ${commit.author.name}`)
428
+ * console.log(`Message: ${commit.message}`)
429
+ * console.log(`Parents: ${commit.parents.length}`)
430
+ * }
431
+ * ```
98
432
  */
99
433
  getCommitObject(sha: string): Promise<CommitObject | null>;
100
434
  /**
101
- * Get a tag object with parsed fields
435
+ * Get a tag object with parsed fields.
436
+ *
437
+ * @description
438
+ * Fetches and parses an annotated tag object, extracting
439
+ * the tagged object SHA, object type, tag name, tagger, and message.
440
+ *
441
+ * @param sha - 40-character SHA-1 hash
442
+ * @returns Parsed TagObject or null
443
+ *
444
+ * @example
445
+ * ```typescript
446
+ * const tag = await store.getTagObject(sha)
447
+ * if (tag) {
448
+ * console.log(`Tag: ${tag.name}`)
449
+ * console.log(`Points to: ${tag.object} (${tag.objectType})`)
450
+ * console.log(`Tagger: ${tag.tagger?.name}`)
451
+ * }
452
+ * ```
102
453
  */
103
454
  getTagObject(sha: string): Promise<TagObject | null>;
104
455
  /**
105
- * Get raw serialized object with git header
456
+ * Get raw serialized object with Git header.
457
+ *
458
+ * @description
459
+ * Returns the complete Git object format including header:
460
+ * "{type} {size}\0{content}"
461
+ *
462
+ * This is the format used for hashing and storage in pack files.
463
+ *
464
+ * @param sha - 40-character SHA-1 hash
465
+ * @returns Complete object with Git header or null
466
+ *
467
+ * @example
468
+ * ```typescript
469
+ * const raw = await store.getRawObject(sha)
470
+ * if (raw) {
471
+ * // Can be written directly to a pack file or loose object
472
+ * }
473
+ * ```
106
474
  */
107
475
  getRawObject(sha: string): Promise<Uint8Array | null>;
108
476
  /**
109
- * Log operation to WAL
477
+ * Log operation to WAL.
478
+ *
479
+ * @description
480
+ * Writes an operation entry to the write-ahead log for durability.
481
+ * The WAL ensures operations can be recovered after crashes.
482
+ *
483
+ * @param operation - Operation type ('PUT', 'DELETE', etc.)
484
+ * @param sha - Object SHA being operated on
485
+ * @param type - Object type
486
+ * @param _data - Object data (not stored in WAL, just for signature compatibility)
487
+ * @internal
110
488
  */
111
489
  private logToWAL;
112
490
  }
@@ -1 +1 @@
1
- {"version":3,"file":"object-store.d.ts","sourceRoot":"","sources":["../../src/durable-object/object-store.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"object-store.d.ts","sourceRoot":"","sources":["../../src/durable-object/object-store.ts"],"names":[],"mappings":"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"}