gitx.do 0.0.2 → 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.
- package/dist/cli/commands/blame.d.ts +259 -0
- package/dist/cli/commands/blame.d.ts.map +1 -0
- package/dist/cli/commands/blame.js +609 -0
- package/dist/cli/commands/blame.js.map +1 -0
- package/dist/cli/commands/branch.d.ts +249 -0
- package/dist/cli/commands/branch.d.ts.map +1 -0
- package/dist/cli/commands/branch.js +693 -0
- package/dist/cli/commands/branch.js.map +1 -0
- package/dist/cli/commands/commit.d.ts +182 -0
- package/dist/cli/commands/commit.d.ts.map +1 -0
- package/dist/cli/commands/commit.js +437 -0
- package/dist/cli/commands/commit.js.map +1 -0
- package/dist/cli/commands/diff.d.ts +464 -0
- package/dist/cli/commands/diff.d.ts.map +1 -0
- package/dist/cli/commands/diff.js +958 -0
- package/dist/cli/commands/diff.js.map +1 -0
- package/dist/cli/commands/log.d.ts +239 -0
- package/dist/cli/commands/log.d.ts.map +1 -0
- package/dist/cli/commands/log.js +535 -0
- package/dist/cli/commands/log.js.map +1 -0
- package/dist/cli/commands/review.d.ts +457 -0
- package/dist/cli/commands/review.d.ts.map +1 -0
- package/dist/cli/commands/review.js +533 -0
- package/dist/cli/commands/review.js.map +1 -0
- package/dist/cli/commands/status.d.ts +269 -0
- package/dist/cli/commands/status.d.ts.map +1 -0
- package/dist/cli/commands/status.js +493 -0
- package/dist/cli/commands/status.js.map +1 -0
- package/dist/cli/commands/web.d.ts +199 -0
- package/dist/cli/commands/web.d.ts.map +1 -0
- package/dist/cli/commands/web.js +696 -0
- package/dist/cli/commands/web.js.map +1 -0
- package/dist/cli/fs-adapter.d.ts +656 -0
- package/dist/cli/fs-adapter.d.ts.map +1 -0
- package/dist/cli/fs-adapter.js +1179 -0
- package/dist/cli/fs-adapter.js.map +1 -0
- package/dist/cli/index.d.ts +387 -0
- package/dist/cli/index.d.ts.map +1 -0
- package/dist/cli/index.js +523 -0
- package/dist/cli/index.js.map +1 -0
- package/dist/cli/ui/components/DiffView.d.ts +7 -0
- package/dist/cli/ui/components/DiffView.d.ts.map +1 -0
- package/dist/cli/ui/components/DiffView.js +11 -0
- package/dist/cli/ui/components/DiffView.js.map +1 -0
- package/dist/cli/ui/components/ErrorDisplay.d.ts +6 -0
- package/dist/cli/ui/components/ErrorDisplay.d.ts.map +1 -0
- package/dist/cli/ui/components/ErrorDisplay.js +11 -0
- package/dist/cli/ui/components/ErrorDisplay.js.map +1 -0
- package/dist/cli/ui/components/FuzzySearch.d.ts +9 -0
- package/dist/cli/ui/components/FuzzySearch.d.ts.map +1 -0
- package/dist/cli/ui/components/FuzzySearch.js +12 -0
- package/dist/cli/ui/components/FuzzySearch.js.map +1 -0
- package/dist/cli/ui/components/LoadingSpinner.d.ts +6 -0
- package/dist/cli/ui/components/LoadingSpinner.d.ts.map +1 -0
- package/dist/cli/ui/components/LoadingSpinner.js +10 -0
- package/dist/cli/ui/components/LoadingSpinner.js.map +1 -0
- package/dist/cli/ui/components/NavigationList.d.ts +9 -0
- package/dist/cli/ui/components/NavigationList.d.ts.map +1 -0
- package/dist/cli/ui/components/NavigationList.js +11 -0
- package/dist/cli/ui/components/NavigationList.js.map +1 -0
- package/dist/cli/ui/components/ScrollableContent.d.ts +8 -0
- package/dist/cli/ui/components/ScrollableContent.d.ts.map +1 -0
- package/dist/cli/ui/components/ScrollableContent.js +11 -0
- package/dist/cli/ui/components/ScrollableContent.js.map +1 -0
- package/dist/cli/ui/components/index.d.ts +7 -0
- package/dist/cli/ui/components/index.d.ts.map +1 -0
- package/dist/cli/ui/components/index.js +9 -0
- package/dist/cli/ui/components/index.js.map +1 -0
- package/dist/cli/ui/terminal-ui.d.ts +52 -0
- package/dist/cli/ui/terminal-ui.d.ts.map +1 -0
- package/dist/cli/ui/terminal-ui.js +121 -0
- package/dist/cli/ui/terminal-ui.js.map +1 -0
- package/dist/durable-object/object-store.d.ts +401 -23
- package/dist/durable-object/object-store.d.ts.map +1 -1
- package/dist/durable-object/object-store.js +414 -25
- package/dist/durable-object/object-store.js.map +1 -1
- package/dist/durable-object/schema.d.ts +188 -0
- package/dist/durable-object/schema.d.ts.map +1 -1
- package/dist/durable-object/schema.js +160 -0
- package/dist/durable-object/schema.js.map +1 -1
- package/dist/durable-object/wal.d.ts +336 -31
- package/dist/durable-object/wal.d.ts.map +1 -1
- package/dist/durable-object/wal.js +272 -27
- package/dist/durable-object/wal.js.map +1 -1
- package/dist/index.d.ts +379 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +379 -7
- package/dist/index.js.map +1 -1
- package/dist/mcp/adapter.d.ts +579 -38
- package/dist/mcp/adapter.d.ts.map +1 -1
- package/dist/mcp/adapter.js +426 -33
- package/dist/mcp/adapter.js.map +1 -1
- package/dist/mcp/sandbox.d.ts +532 -29
- package/dist/mcp/sandbox.d.ts.map +1 -1
- package/dist/mcp/sandbox.js +389 -22
- package/dist/mcp/sandbox.js.map +1 -1
- package/dist/mcp/sdk-adapter.d.ts +478 -56
- package/dist/mcp/sdk-adapter.d.ts.map +1 -1
- package/dist/mcp/sdk-adapter.js +346 -44
- package/dist/mcp/sdk-adapter.js.map +1 -1
- package/dist/mcp/tools.d.ts +445 -30
- package/dist/mcp/tools.d.ts.map +1 -1
- package/dist/mcp/tools.js +363 -33
- package/dist/mcp/tools.js.map +1 -1
- package/dist/ops/blame.d.ts +424 -21
- package/dist/ops/blame.d.ts.map +1 -1
- package/dist/ops/blame.js +303 -20
- package/dist/ops/blame.js.map +1 -1
- package/dist/ops/branch.d.ts +583 -32
- package/dist/ops/branch.d.ts.map +1 -1
- package/dist/ops/branch.js +365 -23
- package/dist/ops/branch.js.map +1 -1
- package/dist/ops/commit-traversal.d.ts +164 -24
- package/dist/ops/commit-traversal.d.ts.map +1 -1
- package/dist/ops/commit-traversal.js +68 -2
- package/dist/ops/commit-traversal.js.map +1 -1
- package/dist/ops/commit.d.ts +387 -53
- package/dist/ops/commit.d.ts.map +1 -1
- package/dist/ops/commit.js +249 -29
- package/dist/ops/commit.js.map +1 -1
- package/dist/ops/merge-base.d.ts +195 -21
- package/dist/ops/merge-base.d.ts.map +1 -1
- package/dist/ops/merge-base.js +122 -12
- package/dist/ops/merge-base.js.map +1 -1
- package/dist/ops/merge.d.ts +600 -130
- package/dist/ops/merge.d.ts.map +1 -1
- package/dist/ops/merge.js +408 -60
- package/dist/ops/merge.js.map +1 -1
- package/dist/ops/tag.d.ts +67 -2
- package/dist/ops/tag.d.ts.map +1 -1
- package/dist/ops/tag.js +42 -1
- package/dist/ops/tag.js.map +1 -1
- package/dist/ops/tree-builder.d.ts +102 -6
- package/dist/ops/tree-builder.d.ts.map +1 -1
- package/dist/ops/tree-builder.js +30 -5
- package/dist/ops/tree-builder.js.map +1 -1
- package/dist/ops/tree-diff.d.ts +50 -2
- package/dist/ops/tree-diff.d.ts.map +1 -1
- package/dist/ops/tree-diff.js +50 -2
- package/dist/ops/tree-diff.js.map +1 -1
- package/dist/pack/delta.d.ts +211 -39
- package/dist/pack/delta.d.ts.map +1 -1
- package/dist/pack/delta.js +232 -46
- package/dist/pack/delta.js.map +1 -1
- package/dist/pack/format.d.ts +390 -28
- package/dist/pack/format.d.ts.map +1 -1
- package/dist/pack/format.js +344 -33
- package/dist/pack/format.js.map +1 -1
- package/dist/pack/full-generation.d.ts +313 -28
- package/dist/pack/full-generation.d.ts.map +1 -1
- package/dist/pack/full-generation.js +238 -19
- package/dist/pack/full-generation.js.map +1 -1
- package/dist/pack/generation.d.ts +346 -23
- package/dist/pack/generation.d.ts.map +1 -1
- package/dist/pack/generation.js +269 -21
- package/dist/pack/generation.js.map +1 -1
- package/dist/pack/index.d.ts +407 -86
- package/dist/pack/index.d.ts.map +1 -1
- package/dist/pack/index.js +351 -70
- package/dist/pack/index.js.map +1 -1
- package/dist/refs/branch.d.ts +517 -71
- package/dist/refs/branch.d.ts.map +1 -1
- package/dist/refs/branch.js +410 -26
- package/dist/refs/branch.js.map +1 -1
- package/dist/refs/storage.d.ts +610 -57
- package/dist/refs/storage.d.ts.map +1 -1
- package/dist/refs/storage.js +481 -29
- package/dist/refs/storage.js.map +1 -1
- package/dist/refs/tag.d.ts +677 -67
- package/dist/refs/tag.d.ts.map +1 -1
- package/dist/refs/tag.js +497 -30
- package/dist/refs/tag.js.map +1 -1
- package/dist/storage/lru-cache.d.ts +556 -53
- package/dist/storage/lru-cache.d.ts.map +1 -1
- package/dist/storage/lru-cache.js +439 -36
- package/dist/storage/lru-cache.js.map +1 -1
- package/dist/storage/object-index.d.ts +483 -38
- package/dist/storage/object-index.d.ts.map +1 -1
- package/dist/storage/object-index.js +388 -22
- package/dist/storage/object-index.js.map +1 -1
- package/dist/storage/r2-pack.d.ts +957 -94
- package/dist/storage/r2-pack.d.ts.map +1 -1
- package/dist/storage/r2-pack.js +756 -48
- package/dist/storage/r2-pack.js.map +1 -1
- package/dist/tiered/cdc-pipeline.d.ts +1610 -38
- package/dist/tiered/cdc-pipeline.d.ts.map +1 -1
- package/dist/tiered/cdc-pipeline.js +1131 -22
- package/dist/tiered/cdc-pipeline.js.map +1 -1
- package/dist/tiered/migration.d.ts +903 -41
- package/dist/tiered/migration.d.ts.map +1 -1
- package/dist/tiered/migration.js +646 -24
- package/dist/tiered/migration.js.map +1 -1
- package/dist/tiered/parquet-writer.d.ts +944 -47
- package/dist/tiered/parquet-writer.d.ts.map +1 -1
- package/dist/tiered/parquet-writer.js +667 -39
- package/dist/tiered/parquet-writer.js.map +1 -1
- package/dist/tiered/read-path.d.ts +728 -34
- package/dist/tiered/read-path.d.ts.map +1 -1
- package/dist/tiered/read-path.js +310 -27
- package/dist/tiered/read-path.js.map +1 -1
- package/dist/types/objects.d.ts +457 -0
- package/dist/types/objects.d.ts.map +1 -1
- package/dist/types/objects.js +305 -4
- package/dist/types/objects.js.map +1 -1
- package/dist/types/storage.d.ts +407 -35
- package/dist/types/storage.d.ts.map +1 -1
- package/dist/types/storage.js +27 -3
- package/dist/types/storage.js.map +1 -1
- package/dist/utils/hash.d.ts +133 -12
- package/dist/utils/hash.d.ts.map +1 -1
- package/dist/utils/hash.js +133 -12
- package/dist/utils/hash.js.map +1 -1
- package/dist/utils/sha1.d.ts +102 -9
- package/dist/utils/sha1.d.ts.map +1 -1
- package/dist/utils/sha1.js +114 -11
- package/dist/utils/sha1.js.map +1 -1
- package/dist/wire/capabilities.d.ts +896 -88
- package/dist/wire/capabilities.d.ts.map +1 -1
- package/dist/wire/capabilities.js +566 -62
- package/dist/wire/capabilities.js.map +1 -1
- package/dist/wire/pkt-line.d.ts +293 -15
- package/dist/wire/pkt-line.d.ts.map +1 -1
- package/dist/wire/pkt-line.js +251 -15
- package/dist/wire/pkt-line.js.map +1 -1
- package/dist/wire/receive-pack.d.ts +814 -64
- package/dist/wire/receive-pack.d.ts.map +1 -1
- package/dist/wire/receive-pack.js +542 -41
- package/dist/wire/receive-pack.js.map +1 -1
- package/dist/wire/smart-http.d.ts +575 -97
- package/dist/wire/smart-http.d.ts.map +1 -1
- package/dist/wire/smart-http.js +337 -46
- package/dist/wire/smart-http.js.map +1 -1
- package/dist/wire/upload-pack.d.ts +492 -98
- package/dist/wire/upload-pack.d.ts.map +1 -1
- package/dist/wire/upload-pack.js +347 -59
- package/dist/wire/upload-pack.js.map +1 -1
- package/package.json +1 -1
|
@@ -1,30 +1,136 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* @fileoverview Write-Ahead Log (WAL) Manager for Transaction Durability
|
|
3
|
+
*
|
|
4
|
+
* This module provides a Write-Ahead Log implementation for ensuring durability
|
|
5
|
+
* and crash recovery in the Git object storage. All operations are logged before
|
|
6
|
+
* being applied, allowing recovery after failures.
|
|
7
|
+
*
|
|
8
|
+
* **Key Features**:
|
|
9
|
+
* - Transaction support with begin/commit/rollback semantics
|
|
10
|
+
* - Checkpoint creation for efficient recovery
|
|
11
|
+
* - WAL truncation after successful checkpoints
|
|
12
|
+
* - Unflushed entry recovery for crash recovery
|
|
13
|
+
*
|
|
14
|
+
* @module durable-object/wal
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```typescript
|
|
18
|
+
* import { WALManager } from './durable-object/wal'
|
|
19
|
+
*
|
|
20
|
+
* const wal = new WALManager(storage)
|
|
21
|
+
*
|
|
22
|
+
* // Simple operation logging
|
|
23
|
+
* const entryId = await wal.append('PUT', payload)
|
|
24
|
+
*
|
|
25
|
+
* // Transaction support
|
|
26
|
+
* const txId = await wal.beginTransaction()
|
|
27
|
+
* await wal.append('PUT', payload1, txId)
|
|
28
|
+
* await wal.append('PUT', payload2, txId)
|
|
29
|
+
* await wal.commitTransaction(txId)
|
|
30
|
+
*
|
|
31
|
+
* // Create checkpoint for recovery point
|
|
32
|
+
* const checkpoint = await wal.createCheckpoint()
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
// ============================================================================
|
|
36
|
+
// Helper Functions
|
|
37
|
+
// ============================================================================
|
|
38
|
+
/**
|
|
39
|
+
* Generate a unique transaction ID.
|
|
40
|
+
*
|
|
41
|
+
* @description
|
|
42
|
+
* Creates a unique identifier for transactions using timestamp
|
|
43
|
+
* and random components to avoid collisions.
|
|
44
|
+
*
|
|
45
|
+
* @returns Unique transaction ID string (e.g., 'tx-lxyz123-abc12345')
|
|
46
|
+
* @internal
|
|
3
47
|
*/
|
|
4
48
|
function generateTransactionId() {
|
|
5
49
|
const timestamp = Date.now().toString(36);
|
|
6
50
|
const random = Math.random().toString(36).substring(2, 10);
|
|
7
51
|
return `tx-${timestamp}-${random}`;
|
|
8
52
|
}
|
|
53
|
+
// ============================================================================
|
|
54
|
+
// WALManager Class
|
|
55
|
+
// ============================================================================
|
|
9
56
|
/**
|
|
10
|
-
*
|
|
57
|
+
* Write-Ahead Log Manager for transaction durability.
|
|
11
58
|
*
|
|
59
|
+
* @description
|
|
12
60
|
* Provides durability guarantees by logging all operations before they are applied.
|
|
13
61
|
* Supports transactions with begin/commit/rollback semantics and checkpoint management.
|
|
62
|
+
*
|
|
63
|
+
* **Usage Pattern**:
|
|
64
|
+
* 1. Log operations using `append()` before applying them
|
|
65
|
+
* 2. Use transactions for atomic multi-operation changes
|
|
66
|
+
* 3. Create checkpoints periodically for efficient recovery
|
|
67
|
+
* 4. Truncate WAL after successful checkpoints
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* ```typescript
|
|
71
|
+
* const wal = new WALManager(storage)
|
|
72
|
+
*
|
|
73
|
+
* // Single operation
|
|
74
|
+
* const payload = new TextEncoder().encode(JSON.stringify({ sha: 'abc123' }))
|
|
75
|
+
* const id = await wal.append('PUT', payload)
|
|
76
|
+
*
|
|
77
|
+
* // Transaction
|
|
78
|
+
* const txId = await wal.beginTransaction()
|
|
79
|
+
* try {
|
|
80
|
+
* await wal.append('PUT', payload1, txId)
|
|
81
|
+
* await wal.append('PUT', payload2, txId)
|
|
82
|
+
* await wal.commitTransaction(txId)
|
|
83
|
+
* } catch (e) {
|
|
84
|
+
* await wal.rollbackTransaction(txId)
|
|
85
|
+
* throw e
|
|
86
|
+
* }
|
|
87
|
+
*
|
|
88
|
+
* // Checkpoint and cleanup
|
|
89
|
+
* const checkpoint = await wal.createCheckpoint()
|
|
90
|
+
* await wal.truncateBeforeCheckpoint(checkpoint)
|
|
91
|
+
* ```
|
|
14
92
|
*/
|
|
15
93
|
export class WALManager {
|
|
94
|
+
/** Durable Object storage interface */
|
|
16
95
|
storage;
|
|
96
|
+
/** In-memory transaction tracking */
|
|
17
97
|
transactions = new Map();
|
|
98
|
+
/** Current WAL position for entry ID assignment */
|
|
18
99
|
currentWalPosition = 0;
|
|
100
|
+
/**
|
|
101
|
+
* Create a new WALManager.
|
|
102
|
+
*
|
|
103
|
+
* @param storage - Durable Object storage interface with SQL support
|
|
104
|
+
*/
|
|
19
105
|
constructor(storage) {
|
|
20
106
|
this.storage = storage;
|
|
21
107
|
}
|
|
22
108
|
/**
|
|
23
|
-
* Append an operation to the WAL
|
|
24
|
-
*
|
|
25
|
-
* @
|
|
26
|
-
*
|
|
109
|
+
* Append an operation to the WAL.
|
|
110
|
+
*
|
|
111
|
+
* @description
|
|
112
|
+
* Logs an operation to the WAL before it is applied. Operations can
|
|
113
|
+
* optionally be associated with a transaction for atomic commit/rollback.
|
|
114
|
+
*
|
|
115
|
+
* @param operation - The type of operation being logged
|
|
116
|
+
* @param payload - Binary data describing the operation (usually JSON-encoded)
|
|
117
|
+
* @param transactionId - Optional transaction ID to associate with this operation
|
|
27
118
|
* @returns The ID of the appended WAL entry
|
|
119
|
+
*
|
|
120
|
+
* @example
|
|
121
|
+
* ```typescript
|
|
122
|
+
* // Simple append
|
|
123
|
+
* const payload = new TextEncoder().encode(JSON.stringify({
|
|
124
|
+
* sha: 'abc123',
|
|
125
|
+
* type: 'blob',
|
|
126
|
+
* timestamp: Date.now()
|
|
127
|
+
* }))
|
|
128
|
+
* const entryId = await wal.append('PUT', payload)
|
|
129
|
+
*
|
|
130
|
+
* // Append within transaction
|
|
131
|
+
* const txId = await wal.beginTransaction()
|
|
132
|
+
* await wal.append('PUT', payload, txId)
|
|
133
|
+
* ```
|
|
28
134
|
*/
|
|
29
135
|
async append(operation, payload, transactionId) {
|
|
30
136
|
const result = this.storage.sql.exec('INSERT INTO wal (operation, payload, transaction_id) VALUES (?, ?, ?)', operation, payload, transactionId ?? null);
|
|
@@ -41,8 +147,19 @@ export class WALManager {
|
|
|
41
147
|
return entryId;
|
|
42
148
|
}
|
|
43
149
|
/**
|
|
44
|
-
* Flush all unflushed WAL entries
|
|
45
|
-
*
|
|
150
|
+
* Flush all unflushed WAL entries.
|
|
151
|
+
*
|
|
152
|
+
* @description
|
|
153
|
+
* Marks all unflushed entries as flushed, indicating they have been
|
|
154
|
+
* durably persisted. This is typically called before creating a checkpoint.
|
|
155
|
+
*
|
|
156
|
+
* @returns The number of entries that were flushed
|
|
157
|
+
*
|
|
158
|
+
* @example
|
|
159
|
+
* ```typescript
|
|
160
|
+
* const count = await wal.flush()
|
|
161
|
+
* console.log(`Flushed ${count} entries`)
|
|
162
|
+
* ```
|
|
46
163
|
*/
|
|
47
164
|
async flush() {
|
|
48
165
|
// Get count of unflushed entries
|
|
@@ -57,8 +174,22 @@ export class WALManager {
|
|
|
57
174
|
return count;
|
|
58
175
|
}
|
|
59
176
|
/**
|
|
60
|
-
* Recover unflushed WAL entries for replay
|
|
61
|
-
*
|
|
177
|
+
* Recover unflushed WAL entries for replay.
|
|
178
|
+
*
|
|
179
|
+
* @description
|
|
180
|
+
* Returns all unflushed WAL entries in order for replay during
|
|
181
|
+
* crash recovery. Entries should be replayed in order by ID.
|
|
182
|
+
*
|
|
183
|
+
* @returns Array of unflushed WAL entries sorted by ID
|
|
184
|
+
*
|
|
185
|
+
* @example
|
|
186
|
+
* ```typescript
|
|
187
|
+
* const entries = await wal.recover()
|
|
188
|
+
* for (const entry of entries) {
|
|
189
|
+
* console.log(`Replaying ${entry.operation} ${entry.id}`)
|
|
190
|
+
* // Apply the operation...
|
|
191
|
+
* }
|
|
192
|
+
* ```
|
|
62
193
|
*/
|
|
63
194
|
async recover() {
|
|
64
195
|
const result = this.storage.sql.exec('SELECT id, operation, payload, transaction_id, created_at, flushed FROM wal WHERE flushed = 0 ORDER BY id ASC');
|
|
@@ -66,8 +197,25 @@ export class WALManager {
|
|
|
66
197
|
return rows.sort((a, b) => a.id - b.id);
|
|
67
198
|
}
|
|
68
199
|
/**
|
|
69
|
-
* Begin a new transaction
|
|
70
|
-
*
|
|
200
|
+
* Begin a new transaction.
|
|
201
|
+
*
|
|
202
|
+
* @description
|
|
203
|
+
* Starts a new transaction and returns its ID. Operations appended
|
|
204
|
+
* with this transaction ID will be atomically committed or rolled back.
|
|
205
|
+
*
|
|
206
|
+
* @returns The unique transaction ID
|
|
207
|
+
*
|
|
208
|
+
* @example
|
|
209
|
+
* ```typescript
|
|
210
|
+
* const txId = await wal.beginTransaction()
|
|
211
|
+
* try {
|
|
212
|
+
* await wal.append('PUT', payload1, txId)
|
|
213
|
+
* await wal.append('DELETE', payload2, txId)
|
|
214
|
+
* await wal.commitTransaction(txId)
|
|
215
|
+
* } catch (e) {
|
|
216
|
+
* await wal.rollbackTransaction(txId)
|
|
217
|
+
* }
|
|
218
|
+
* ```
|
|
71
219
|
*/
|
|
72
220
|
async beginTransaction() {
|
|
73
221
|
const txId = generateTransactionId();
|
|
@@ -85,8 +233,22 @@ export class WALManager {
|
|
|
85
233
|
return txId;
|
|
86
234
|
}
|
|
87
235
|
/**
|
|
88
|
-
* Commit a transaction
|
|
89
|
-
*
|
|
236
|
+
* Commit a transaction.
|
|
237
|
+
*
|
|
238
|
+
* @description
|
|
239
|
+
* Commits all operations in the transaction, making them permanent.
|
|
240
|
+
* After commit, the transaction cannot be rolled back.
|
|
241
|
+
*
|
|
242
|
+
* @param transactionId - The transaction ID to commit
|
|
243
|
+
* @throws Error if transaction not found or not active
|
|
244
|
+
*
|
|
245
|
+
* @example
|
|
246
|
+
* ```typescript
|
|
247
|
+
* const txId = await wal.beginTransaction()
|
|
248
|
+
* await wal.append('PUT', payload, txId)
|
|
249
|
+
* await wal.commitTransaction(txId)
|
|
250
|
+
* // Transaction is now committed
|
|
251
|
+
* ```
|
|
90
252
|
*/
|
|
91
253
|
async commitTransaction(transactionId) {
|
|
92
254
|
const tx = this.transactions.get(transactionId);
|
|
@@ -109,8 +271,26 @@ export class WALManager {
|
|
|
109
271
|
this.storage.sql.exec('UPDATE transactions SET state = ? WHERE id = ?', 'COMMITTED', transactionId);
|
|
110
272
|
}
|
|
111
273
|
/**
|
|
112
|
-
* Rollback a transaction
|
|
113
|
-
*
|
|
274
|
+
* Rollback a transaction.
|
|
275
|
+
*
|
|
276
|
+
* @description
|
|
277
|
+
* Rolls back all operations in the transaction, undoing their effects.
|
|
278
|
+
* After rollback, the transaction is marked as rolled back.
|
|
279
|
+
*
|
|
280
|
+
* @param transactionId - The transaction ID to rollback
|
|
281
|
+
* @throws Error if transaction not found or not active
|
|
282
|
+
*
|
|
283
|
+
* @example
|
|
284
|
+
* ```typescript
|
|
285
|
+
* const txId = await wal.beginTransaction()
|
|
286
|
+
* try {
|
|
287
|
+
* await wal.append('PUT', payload, txId)
|
|
288
|
+
* throw new Error('Something went wrong')
|
|
289
|
+
* } catch (e) {
|
|
290
|
+
* await wal.rollbackTransaction(txId)
|
|
291
|
+
* // All operations in transaction are undone
|
|
292
|
+
* }
|
|
293
|
+
* ```
|
|
114
294
|
*/
|
|
115
295
|
async rollbackTransaction(transactionId) {
|
|
116
296
|
const tx = this.transactions.get(transactionId);
|
|
@@ -134,9 +314,22 @@ export class WALManager {
|
|
|
134
314
|
this.storage.sql.exec('UPDATE transactions SET state = ? WHERE id = ?', 'ROLLED_BACK', transactionId);
|
|
135
315
|
}
|
|
136
316
|
/**
|
|
137
|
-
* Get the state of a transaction
|
|
138
|
-
*
|
|
139
|
-
* @
|
|
317
|
+
* Get the state of a transaction.
|
|
318
|
+
*
|
|
319
|
+
* @description
|
|
320
|
+
* Returns the current state of a transaction, checking both in-memory
|
|
321
|
+
* cache and persistent storage.
|
|
322
|
+
*
|
|
323
|
+
* @param transactionId - The transaction ID to check
|
|
324
|
+
* @returns Transaction state or null if not found
|
|
325
|
+
*
|
|
326
|
+
* @example
|
|
327
|
+
* ```typescript
|
|
328
|
+
* const state = await wal.getTransactionState(txId)
|
|
329
|
+
* if (state === 'COMMITTED') {
|
|
330
|
+
* console.log('Transaction was committed')
|
|
331
|
+
* }
|
|
332
|
+
* ```
|
|
140
333
|
*/
|
|
141
334
|
async getTransactionState(transactionId) {
|
|
142
335
|
const tx = this.transactions.get(transactionId);
|
|
@@ -148,9 +341,21 @@ export class WALManager {
|
|
|
148
341
|
return rows.length > 0 ? rows[0].state : null;
|
|
149
342
|
}
|
|
150
343
|
/**
|
|
151
|
-
* Create a checkpoint at the current WAL position
|
|
152
|
-
*
|
|
344
|
+
* Create a checkpoint at the current WAL position.
|
|
345
|
+
*
|
|
346
|
+
* @description
|
|
347
|
+
* Creates a checkpoint marking a consistent point where all prior
|
|
348
|
+
* operations have been successfully applied. Flushes pending entries first.
|
|
349
|
+
*
|
|
350
|
+
* @param metadata - Optional descriptive metadata for the checkpoint
|
|
153
351
|
* @returns The created checkpoint
|
|
352
|
+
*
|
|
353
|
+
* @example
|
|
354
|
+
* ```typescript
|
|
355
|
+
* // Create checkpoint after batch of operations
|
|
356
|
+
* const checkpoint = await wal.createCheckpoint('Post-push checkpoint')
|
|
357
|
+
* console.log(`Checkpoint at position ${checkpoint.walPosition}`)
|
|
358
|
+
* ```
|
|
154
359
|
*/
|
|
155
360
|
async createCheckpoint(metadata) {
|
|
156
361
|
// Flush all pending entries before creating checkpoint
|
|
@@ -172,8 +377,21 @@ export class WALManager {
|
|
|
172
377
|
return checkpoint;
|
|
173
378
|
}
|
|
174
379
|
/**
|
|
175
|
-
* Get the most recent checkpoint
|
|
176
|
-
*
|
|
380
|
+
* Get the most recent checkpoint.
|
|
381
|
+
*
|
|
382
|
+
* @description
|
|
383
|
+
* Returns the last checkpoint created, or null if none exist.
|
|
384
|
+
* Useful for determining where to start recovery.
|
|
385
|
+
*
|
|
386
|
+
* @returns The last checkpoint or null
|
|
387
|
+
*
|
|
388
|
+
* @example
|
|
389
|
+
* ```typescript
|
|
390
|
+
* const lastCheckpoint = await wal.getLastCheckpoint()
|
|
391
|
+
* if (lastCheckpoint) {
|
|
392
|
+
* console.log(`Last checkpoint at position ${lastCheckpoint.walPosition}`)
|
|
393
|
+
* }
|
|
394
|
+
* ```
|
|
177
395
|
*/
|
|
178
396
|
async getLastCheckpoint() {
|
|
179
397
|
const result = this.storage.sql.exec('SELECT id, wal_position, created_at, metadata FROM checkpoints ORDER BY id DESC LIMIT 1');
|
|
@@ -181,15 +399,42 @@ export class WALManager {
|
|
|
181
399
|
return rows.length > 0 ? rows[0] : null;
|
|
182
400
|
}
|
|
183
401
|
/**
|
|
184
|
-
* Truncate WAL entries before a checkpoint
|
|
185
|
-
*
|
|
402
|
+
* Truncate WAL entries before a checkpoint.
|
|
403
|
+
*
|
|
404
|
+
* @description
|
|
405
|
+
* Removes all WAL entries before (and including) the checkpoint position
|
|
406
|
+
* that have been flushed. This reclaims space after a successful checkpoint.
|
|
407
|
+
*
|
|
408
|
+
* **Note**: Only truncates flushed entries to avoid data loss.
|
|
409
|
+
*
|
|
410
|
+
* @param checkpoint - The checkpoint to truncate before
|
|
411
|
+
*
|
|
412
|
+
* @example
|
|
413
|
+
* ```typescript
|
|
414
|
+
* const checkpoint = await wal.createCheckpoint()
|
|
415
|
+
* // After verifying all operations are applied...
|
|
416
|
+
* await wal.truncateBeforeCheckpoint(checkpoint)
|
|
417
|
+
* ```
|
|
186
418
|
*/
|
|
187
419
|
async truncateBeforeCheckpoint(checkpoint) {
|
|
188
420
|
this.storage.sql.exec('DELETE FROM wal WHERE id <= ? AND flushed = 1', checkpoint.walPosition);
|
|
189
421
|
}
|
|
190
422
|
/**
|
|
191
|
-
* Get the count of unflushed WAL entries
|
|
192
|
-
*
|
|
423
|
+
* Get the count of unflushed WAL entries.
|
|
424
|
+
*
|
|
425
|
+
* @description
|
|
426
|
+
* Returns the number of WAL entries that have not yet been flushed.
|
|
427
|
+
* Useful for monitoring WAL growth and deciding when to flush.
|
|
428
|
+
*
|
|
429
|
+
* @returns Number of unflushed entries
|
|
430
|
+
*
|
|
431
|
+
* @example
|
|
432
|
+
* ```typescript
|
|
433
|
+
* const count = await wal.getUnflushedCount()
|
|
434
|
+
* if (count > 1000) {
|
|
435
|
+
* await wal.flush()
|
|
436
|
+
* }
|
|
437
|
+
* ```
|
|
193
438
|
*/
|
|
194
439
|
async getUnflushedCount() {
|
|
195
440
|
const result = this.storage.sql.exec('SELECT COUNT(*) as count FROM wal WHERE flushed = 0');
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"wal.js","sourceRoot":"","sources":["../../src/durable-object/wal.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"wal.js","sourceRoot":"","sources":["../../src/durable-object/wal.ts"],"names":[],"mappings":"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"}
|