@framers/sql-storage-adapter 0.1.0

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 (83) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +363 -0
  3. package/dist/adapters/baseStorageAdapter.d.ts +204 -0
  4. package/dist/adapters/baseStorageAdapter.d.ts.map +1 -0
  5. package/dist/adapters/baseStorageAdapter.js +364 -0
  6. package/dist/adapters/baseStorageAdapter.js.map +1 -0
  7. package/dist/adapters/betterSqliteAdapter.d.ts +64 -0
  8. package/dist/adapters/betterSqliteAdapter.d.ts.map +1 -0
  9. package/dist/adapters/betterSqliteAdapter.js +206 -0
  10. package/dist/adapters/betterSqliteAdapter.js.map +1 -0
  11. package/dist/adapters/capacitorSqliteAdapter.d.ts +33 -0
  12. package/dist/adapters/capacitorSqliteAdapter.d.ts.map +1 -0
  13. package/dist/adapters/capacitorSqliteAdapter.js +95 -0
  14. package/dist/adapters/capacitorSqliteAdapter.js.map +1 -0
  15. package/dist/adapters/postgresAdapter.d.ts +180 -0
  16. package/dist/adapters/postgresAdapter.d.ts.map +1 -0
  17. package/dist/adapters/postgresAdapter.js +271 -0
  18. package/dist/adapters/postgresAdapter.js.map +1 -0
  19. package/dist/adapters/sqlJsAdapter.d.ts +28 -0
  20. package/dist/adapters/sqlJsAdapter.d.ts.map +1 -0
  21. package/dist/adapters/sqlJsAdapter.js +136 -0
  22. package/dist/adapters/sqlJsAdapter.js.map +1 -0
  23. package/dist/adapters/supabase.d.ts +58 -0
  24. package/dist/adapters/supabase.d.ts.map +1 -0
  25. package/dist/adapters/supabase.js +385 -0
  26. package/dist/adapters/supabase.js.map +1 -0
  27. package/dist/database.d.ts +124 -0
  28. package/dist/database.d.ts.map +1 -0
  29. package/dist/database.js +136 -0
  30. package/dist/database.js.map +1 -0
  31. package/dist/index.d.ts +17 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +25 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/resolver.d.ts +24 -0
  36. package/dist/resolver.d.ts.map +1 -0
  37. package/dist/resolver.js +91 -0
  38. package/dist/resolver.js.map +1 -0
  39. package/dist/types/context.d.ts +221 -0
  40. package/dist/types/context.d.ts.map +1 -0
  41. package/dist/types/context.js +9 -0
  42. package/dist/types/context.js.map +1 -0
  43. package/dist/types/events.d.ts +225 -0
  44. package/dist/types/events.d.ts.map +1 -0
  45. package/dist/types/events.js +8 -0
  46. package/dist/types/events.js.map +1 -0
  47. package/dist/types/extensions.d.ts +73 -0
  48. package/dist/types/extensions.d.ts.map +1 -0
  49. package/dist/types/extensions.js +7 -0
  50. package/dist/types/extensions.js.map +1 -0
  51. package/dist/types/limitations.d.ts +46 -0
  52. package/dist/types/limitations.d.ts.map +1 -0
  53. package/dist/types/limitations.js +154 -0
  54. package/dist/types/limitations.js.map +1 -0
  55. package/dist/types.d.ts +235 -0
  56. package/dist/types.d.ts.map +1 -0
  57. package/dist/types.js +18 -0
  58. package/dist/types.js.map +1 -0
  59. package/dist/utils/cloudBackup.d.ts +219 -0
  60. package/dist/utils/cloudBackup.d.ts.map +1 -0
  61. package/dist/utils/cloudBackup.js +289 -0
  62. package/dist/utils/cloudBackup.js.map +1 -0
  63. package/dist/utils/dataExport.d.ts +77 -0
  64. package/dist/utils/dataExport.d.ts.map +1 -0
  65. package/dist/utils/dataExport.js +212 -0
  66. package/dist/utils/dataExport.js.map +1 -0
  67. package/dist/utils/dataImport.d.ts +54 -0
  68. package/dist/utils/dataImport.d.ts.map +1 -0
  69. package/dist/utils/dataImport.js +324 -0
  70. package/dist/utils/dataImport.js.map +1 -0
  71. package/dist/utils/migration.d.ts +89 -0
  72. package/dist/utils/migration.d.ts.map +1 -0
  73. package/dist/utils/migration.js +184 -0
  74. package/dist/utils/migration.js.map +1 -0
  75. package/dist/utils/parameterUtils.d.ts +9 -0
  76. package/dist/utils/parameterUtils.d.ts.map +1 -0
  77. package/dist/utils/parameterUtils.js +17 -0
  78. package/dist/utils/parameterUtils.js.map +1 -0
  79. package/dist/utils/syncManager.d.ts +342 -0
  80. package/dist/utils/syncManager.d.ts.map +1 -0
  81. package/dist/utils/syncManager.js +533 -0
  82. package/dist/utils/syncManager.js.map +1 -0
  83. package/package.json +108 -0
@@ -0,0 +1,235 @@
1
+ /**
2
+ * @packageDocumentation
3
+ * Core type definitions for the SQL storage adapter abstraction.
4
+ *
5
+ * This package provides a unified interface for SQL storage across multiple platforms,
6
+ * with automatic fallback mechanisms and runtime detection.
7
+ */
8
+ /**
9
+ * Supported storage capability flags.
10
+ *
11
+ * These flags indicate what features are available for each adapter implementation.
12
+ * Consumers should check these capabilities before attempting operations that may
13
+ * not be universally supported.
14
+ */
15
+ export type StorageCapability = 'sync' | 'transactions' | 'wal' | 'locks' | 'persistence' | 'streaming' | 'batch' | 'prepared' | 'concurrent' | 'json' | 'arrays';
16
+ /**
17
+ * Parameter payload accepted by storage statements.
18
+ *
19
+ * Parameters can be provided in multiple formats:
20
+ * - Named parameters: `{ name: 'John', age: 30 }` for statements like `WHERE name = @name`
21
+ * - Positional parameters: `['John', 30]` for statements like `WHERE name = ? AND age = ?`
22
+ * - No parameters: `undefined` or `null` for parameterless queries
23
+ */
24
+ export type StorageParameters = undefined | null | Record<string, unknown> | Array<string | number | null | Uint8Array | unknown>;
25
+ /**
26
+ * Result metadata for mutation statements (INSERT, UPDATE, DELETE).
27
+ */
28
+ export interface StorageRunResult {
29
+ /** Number of rows affected by the statement. */
30
+ changes: number;
31
+ /** Row identifier (if available) returned by the underlying engine. */
32
+ lastInsertRowid?: string | number | null;
33
+ }
34
+ /**
35
+ * Batch operation descriptor for bulk operations.
36
+ */
37
+ export interface BatchOperation {
38
+ /** SQL statement to execute */
39
+ statement: string;
40
+ /** Parameters for this specific operation */
41
+ parameters?: StorageParameters;
42
+ }
43
+ /**
44
+ * Result of a batch operation execution.
45
+ */
46
+ export interface BatchResult {
47
+ /** Number of successfully executed operations */
48
+ successful: number;
49
+ /** Number of failed operations */
50
+ failed: number;
51
+ /** Individual results for each operation (if adapter supports it) */
52
+ results?: StorageRunResult[];
53
+ /** Errors for failed operations (if any) */
54
+ errors?: Array<{
55
+ index: number;
56
+ error: Error;
57
+ }>;
58
+ }
59
+ /**
60
+ * Options accepted when opening a storage adapter.
61
+ */
62
+ export interface StorageOpenOptions {
63
+ /** Absolute path to the primary database file (when applicable). */
64
+ filePath?: string;
65
+ /** Connection string (PostgreSQL, etc.). */
66
+ connectionString?: string;
67
+ /** Optional flag to force read-only mode. */
68
+ readOnly?: boolean;
69
+ /** Arbitrary adapter-specific options bag. */
70
+ adapterOptions?: Record<string, unknown>;
71
+ }
72
+ /**
73
+ * Core SQL storage adapter interface.
74
+ *
75
+ * Every adapter implementation must fulfill this contract to ensure
76
+ * compatibility across different SQL backends. Check the `capabilities`
77
+ * property to determine which optional features are supported.
78
+ *
79
+ * ## Error Handling
80
+ * All methods should throw meaningful errors when operations fail.
81
+ * Adapters should not silently fail or return undefined on errors.
82
+ *
83
+ * ## Thread Safety
84
+ * Adapters should document their thread-safety guarantees. SQLite adapters
85
+ * typically don't support concurrent writes, while PostgreSQL does.
86
+ */
87
+ export interface StorageAdapter {
88
+ /** Identifier for logging/diagnostics (e.g., 'better-sqlite3', 'postgres'). */
89
+ readonly kind: string;
90
+ /** Capability flags indicating supported features. */
91
+ readonly capabilities: ReadonlySet<StorageCapability>;
92
+ /**
93
+ * Opens the underlying connection or initializes the backing store.
94
+ *
95
+ * @throws {Error} If connection cannot be established
96
+ * @example
97
+ * await adapter.open({ filePath: '/path/to/db.sqlite3' });
98
+ */
99
+ open(options?: StorageOpenOptions): Promise<void>;
100
+ /**
101
+ * Executes a mutation statement (INSERT, UPDATE, DELETE).
102
+ *
103
+ * @param statement - SQL statement to execute
104
+ * @param parameters - Optional parameters for the statement
105
+ * @returns Metadata about affected rows
106
+ * @throws {Error} If statement execution fails
107
+ * @example
108
+ * const result = await adapter.run('INSERT INTO users (name) VALUES (?)', ['John']);
109
+ * console.log(`Inserted with ID: ${result.lastInsertRowid}`);
110
+ */
111
+ run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
112
+ /**
113
+ * Retrieves a single row (or null if none found).
114
+ *
115
+ * @param statement - SQL SELECT statement
116
+ * @param parameters - Optional parameters for the statement
117
+ * @returns First row or null if no results
118
+ * @throws {Error} If query execution fails
119
+ * @example
120
+ * const user = await adapter.get<User>('SELECT * FROM users WHERE id = ?', [123]);
121
+ */
122
+ get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
123
+ /**
124
+ * Retrieves all rows returned by the statement.
125
+ *
126
+ * WARNING: For large result sets, this loads everything into memory.
127
+ * Consider using streaming (if supported) for large queries.
128
+ *
129
+ * @param statement - SQL SELECT statement
130
+ * @param parameters - Optional parameters for the statement
131
+ * @returns Array of all matching rows (empty array if none)
132
+ * @throws {Error} If query execution fails
133
+ * @example
134
+ * const users = await adapter.all<User>('SELECT * FROM users WHERE age > ?', [18]);
135
+ */
136
+ all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
137
+ /**
138
+ * Executes a script containing multiple SQL statements.
139
+ *
140
+ * Statements are typically delimited by semicolons. This is useful for
141
+ * running migrations or initialization scripts. No results are returned.
142
+ *
143
+ * @param script - SQL script with multiple statements
144
+ * @throws {Error} If any statement in the script fails
145
+ * @example
146
+ * await adapter.exec(`
147
+ * CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
148
+ * CREATE INDEX idx_users_name ON users(name);
149
+ * `);
150
+ */
151
+ exec(script: string): Promise<void>;
152
+ /**
153
+ * Executes a callback within a database transaction.
154
+ *
155
+ * The transaction is automatically committed on success or rolled back
156
+ * on error. Nested transactions may not be supported by all adapters.
157
+ *
158
+ * @param fn - Async callback to execute within the transaction
159
+ * @returns Result of the callback function
160
+ * @throws {Error} Transaction is rolled back and error is re-thrown
161
+ * @example
162
+ * const result = await adapter.transaction(async (trx) => {
163
+ * await trx.run('INSERT INTO accounts (balance) VALUES (?)', [100]);
164
+ * await trx.run('INSERT INTO logs (action) VALUES (?)', ['account_created']);
165
+ * return { success: true };
166
+ * });
167
+ */
168
+ transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
169
+ /**
170
+ * Closes the underlying connection and releases resources.
171
+ *
172
+ * After calling close(), the adapter should not be used again.
173
+ * Always close adapters when done to prevent resource leaks.
174
+ *
175
+ * @example
176
+ * try {
177
+ * await adapter.open();
178
+ * // ... use adapter ...
179
+ * } finally {
180
+ * await adapter.close();
181
+ * }
182
+ */
183
+ close(): Promise<void>;
184
+ /**
185
+ * Executes multiple operations in a batch (if supported).
186
+ *
187
+ * This is more efficient than executing operations individually,
188
+ * especially for bulk inserts. Check if 'batch' capability is present.
189
+ *
190
+ * @param operations - Array of operations to execute
191
+ * @returns Batch execution results
192
+ * @throws {Error} If adapter doesn't support batch operations
193
+ * @example
194
+ * if (adapter.capabilities.has('batch')) {
195
+ * const result = await adapter.batch([
196
+ * { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Alice'] },
197
+ * { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Bob'] }
198
+ * ]);
199
+ * }
200
+ */
201
+ batch?(operations: BatchOperation[]): Promise<BatchResult>;
202
+ /**
203
+ * Returns a prepared statement for repeated execution (if supported).
204
+ *
205
+ * Prepared statements improve performance for frequently executed queries
206
+ * and provide better protection against SQL injection. Check if 'prepared'
207
+ * capability is present.
208
+ *
209
+ * @param statement - SQL statement to prepare
210
+ * @returns Prepared statement handle
211
+ * @throws {Error} If adapter doesn't support prepared statements
212
+ */
213
+ prepare?<T = unknown>(statement: string): PreparedStatement<T>;
214
+ }
215
+ /**
216
+ * Prepared statement interface for repeated query execution.
217
+ */
218
+ export interface PreparedStatement<T = unknown> {
219
+ run(parameters?: StorageParameters): Promise<StorageRunResult>;
220
+ get(parameters?: StorageParameters): Promise<T | null>;
221
+ all(parameters?: StorageParameters): Promise<T[]>;
222
+ finalize(): Promise<void>;
223
+ }
224
+ /**
225
+ * Shape of adapter factories returned by resolver modules.
226
+ */
227
+ export type StorageAdapterFactory = () => Promise<StorageAdapter>;
228
+ /**
229
+ * Error thrown when no adapter can be resolved.
230
+ */
231
+ export declare class StorageResolutionError extends Error {
232
+ readonly causes: unknown[];
233
+ constructor(message: string, causes?: unknown[]);
234
+ }
235
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/dist/types.js ADDED
@@ -0,0 +1,18 @@
1
+ /**
2
+ * @packageDocumentation
3
+ * Core type definitions for the SQL storage adapter abstraction.
4
+ *
5
+ * This package provides a unified interface for SQL storage across multiple platforms,
6
+ * with automatic fallback mechanisms and runtime detection.
7
+ */
8
+ /**
9
+ * Error thrown when no adapter can be resolved.
10
+ */
11
+ export class StorageResolutionError extends Error {
12
+ constructor(message, causes = []) {
13
+ super(message);
14
+ this.causes = causes;
15
+ this.name = 'StorageResolutionError';
16
+ }
17
+ }
18
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6PH;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe,EAAW,SAAoB,EAAE;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QADqB,WAAM,GAAN,MAAM,CAAgB;QAE1D,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Cloud backup utilities for S3, R2, and other object storage providers.
3
+ *
4
+ * This module provides automatic scheduled backups and restore functionality
5
+ * for SQL databases using S3-compatible storage (AWS S3, Cloudflare R2, MinIO, etc.).
6
+ *
7
+ * Features:
8
+ * - Automatic scheduled backups with configurable intervals
9
+ * - Gzip compression to reduce storage costs
10
+ * - Retention policies (automatic cleanup of old backups)
11
+ * - JSON and SQL export formats
12
+ * - Manual backup/restore on demand
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * import { S3Client } from '@aws-sdk/client-s3';
17
+ * import { createCloudBackupManager } from '@framers/sql-storage-adapter';
18
+ *
19
+ * const s3Client = new S3Client({ region: 'us-east-1' });
20
+ * const manager = createCloudBackupManager(db, s3Client, 'my-backups', {
21
+ * interval: 3600000, // 1 hour
22
+ * maxBackups: 24,
23
+ * options: { compression: 'gzip', format: 'json' }
24
+ * });
25
+ *
26
+ * manager.start(); // Auto-schedule backups
27
+ * await manager.backupNow(); // Manual backup
28
+ * await manager.restore('backups/db-2024-01-15.json.gz');
29
+ * ```
30
+ *
31
+ * @module cloudBackup
32
+ */
33
+ import type { StorageAdapter } from '../types';
34
+ /** Supported backup export formats */
35
+ export type BackupFormat = 'json' | 'sql';
36
+ /** Supported compression algorithms */
37
+ export type CompressionType = 'gzip' | 'none';
38
+ /**
39
+ * Generic interface for cloud storage providers.
40
+ *
41
+ * Implement this interface to support custom storage backends
42
+ * beyond S3-compatible services.
43
+ */
44
+ export interface CloudStorageProvider {
45
+ /**
46
+ * Upload data to cloud storage
47
+ * @param key - The storage key/path for the backup
48
+ * @param data - The backup data (string or Buffer)
49
+ */
50
+ upload(key: string, data: string | Buffer): Promise<void>;
51
+ /**
52
+ * Download data from cloud storage
53
+ * @param key - The storage key/path to download
54
+ * @returns The backup data
55
+ */
56
+ download(key: string): Promise<string | Buffer>;
57
+ /**
58
+ * List available backups in cloud storage
59
+ * @param prefix - Optional prefix to filter backups
60
+ * @returns Array of backup keys
61
+ */
62
+ list(prefix?: string): Promise<string[]>;
63
+ /**
64
+ * Delete a backup from cloud storage
65
+ * @param key - The storage key/path to delete
66
+ */
67
+ delete(key: string): Promise<void>;
68
+ }
69
+ /**
70
+ * Configuration options for backup creation
71
+ */
72
+ export interface BackupOptions {
73
+ /** Backup format (json or sql) - default: 'json' */
74
+ format?: BackupFormat;
75
+ /** Compression type - default: 'gzip' */
76
+ compression?: CompressionType;
77
+ /** Tables to include (undefined = all tables) */
78
+ tables?: string[];
79
+ /** Prefix for backup keys - default: 'backups/' */
80
+ prefix?: string;
81
+ /** Include timestamp in backup key - default: true */
82
+ includeTimestamp?: boolean;
83
+ }
84
+ /**
85
+ * Configuration for automatic scheduled backups
86
+ */
87
+ export interface ScheduledBackupConfig {
88
+ /** Backup interval in milliseconds (e.g., 3600000 = 1 hour) */
89
+ interval: number;
90
+ /** Maximum number of backups to keep (older backups auto-deleted) */
91
+ maxBackups?: number;
92
+ /** Backup creation options */
93
+ options?: BackupOptions;
94
+ /** Callback invoked on successful backup */
95
+ onSuccess?: (key: string) => void;
96
+ /** Callback invoked on backup error */
97
+ onError?: (error: Error) => void;
98
+ }
99
+ /**
100
+ * S3-compatible cloud storage provider.
101
+ *
102
+ * Works with AWS S3, Cloudflare R2, MinIO, and other S3-compatible services.
103
+ * Uses the AWS SDK v3 for S3 operations.
104
+ *
105
+ * @example
106
+ * ```typescript
107
+ * import { S3Client } from '@aws-sdk/client-s3';
108
+ *
109
+ * const s3Client = new S3Client({ region: 'us-east-1' });
110
+ * const provider = new S3StorageProvider(s3Client, 'my-bucket');
111
+ *
112
+ * await provider.upload('backups/test.json', JSON.stringify(data));
113
+ * const backups = await provider.list('backups/');
114
+ * ```
115
+ */
116
+ export declare class S3StorageProvider implements CloudStorageProvider {
117
+ private client;
118
+ private bucket;
119
+ /**
120
+ * @param client - AWS SDK S3Client instance
121
+ * @param bucket - S3 bucket name
122
+ */
123
+ constructor(client: {
124
+ send: (command: unknown) => Promise<unknown>;
125
+ }, bucket: string);
126
+ upload(key: string, data: string | Buffer): Promise<void>;
127
+ download(key: string): Promise<string>;
128
+ list(prefix?: string): Promise<string[]>;
129
+ delete(key: string): Promise<void>;
130
+ }
131
+ /**
132
+ * Cloud backup manager for automatic scheduled backups.
133
+ */
134
+ export declare class CloudBackupManager {
135
+ private adapter;
136
+ private storage;
137
+ private config;
138
+ private intervalId?;
139
+ constructor(adapter: StorageAdapter, storage: CloudStorageProvider, config: ScheduledBackupConfig);
140
+ /**
141
+ * Create a backup and upload to cloud storage.
142
+ */
143
+ backup(options?: BackupOptions): Promise<string>;
144
+ /**
145
+ * Restore from a cloud backup.
146
+ */
147
+ restore(key: string): Promise<void>;
148
+ /**
149
+ * List all backups in cloud storage.
150
+ */
151
+ listBackups(prefix?: string): Promise<string[]>;
152
+ /**
153
+ * Delete old backups exceeding maxBackups limit.
154
+ */
155
+ private cleanupOldBackups;
156
+ /**
157
+ * Start automatic scheduled backups.
158
+ */
159
+ start(): void;
160
+ /**
161
+ * Stop automatic scheduled backups.
162
+ */
163
+ stop(): void;
164
+ /**
165
+ * Perform a backup immediately (manual trigger).
166
+ */
167
+ backupNow(options?: BackupOptions): Promise<string>;
168
+ }
169
+ /**
170
+ * Create a cloud backup manager with S3-compatible storage.
171
+ *
172
+ * This is the main factory function for setting up cloud backups.
173
+ * It creates an S3StorageProvider and CloudBackupManager configured
174
+ * with your database and S3-compatible storage.
175
+ *
176
+ * @param adapter - The StorageAdapter instance to backup
177
+ * @param s3Client - AWS SDK S3Client (works with S3, R2, MinIO, etc.)
178
+ * @param bucket - The S3 bucket name
179
+ * @param config - Scheduled backup configuration
180
+ * @returns CloudBackupManager instance ready to start
181
+ *
182
+ * @example AWS S3
183
+ * ```typescript
184
+ * import { S3Client } from '@aws-sdk/client-s3';
185
+ * import { createCloudBackupManager } from '@framers/sql-storage-adapter';
186
+ *
187
+ * const s3 = new S3Client({ region: 'us-east-1' });
188
+ * const manager = createCloudBackupManager(db, s3, 'my-bucket', {
189
+ * interval: 60 * 60 * 1000, // 1 hour
190
+ * maxBackups: 24,
191
+ * options: { compression: 'gzip' }
192
+ * });
193
+ *
194
+ * manager.start();
195
+ * ```
196
+ *
197
+ * @example Cloudflare R2
198
+ * ```typescript
199
+ * import { S3Client } from '@aws-sdk/client-s3';
200
+ *
201
+ * const r2 = new S3Client({
202
+ * region: 'auto',
203
+ * endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
204
+ * credentials: {
205
+ * accessKeyId: process.env.R2_ACCESS_KEY_ID,
206
+ * secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
207
+ * },
208
+ * });
209
+ *
210
+ * const manager = createCloudBackupManager(db, r2, 'backups', {
211
+ * interval: 24 * 60 * 60 * 1000, // Daily
212
+ * maxBackups: 7
213
+ * });
214
+ * ```
215
+ */
216
+ export declare function createCloudBackupManager(adapter: StorageAdapter, s3Client: {
217
+ send: (command: unknown) => Promise<unknown>;
218
+ }, bucket: string, config: ScheduledBackupConfig): CloudBackupManager;
219
+ //# sourceMappingURL=cloudBackup.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cloudBackup.d.ts","sourceRoot":"","sources":["../../src/utils/cloudBackup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI/C,sCAAsC;AACtC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC;AAE1C,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAEhD;;;;OAIG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,yCAAyC;IACzC,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,uCAAuC;IACvC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAkB,YAAW,oBAAoB;IAM1D,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IANhB;;;OAGG;gBAEO,MAAM,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,EACxD,MAAM,EAAE,MAAM;IAGlB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IActC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOzC;AAuBD;;GAEG;AACH,qBAAa,kBAAkB;IAI3B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,UAAU,CAAC,CAAiB;gBAG1B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,qBAAqB;IAGvC;;OAEG;IACG,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAsC1D;;OAEG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzC;;OAEG;IACG,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKrD;;OAEG;YACW,iBAAiB;IAe/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAeb;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;CAG1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE;IAAE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,EAC1D,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,qBAAqB,GAC5B,kBAAkB,CAGpB"}