@gl-life/gl-life-database 1.0.0 → 1.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 (75) hide show
  1. package/API.md +249 -1
  2. package/README.md +67 -0
  3. package/dist/index.cjs +1 -1
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.ts +21 -3
  6. package/dist/index.js +1 -1
  7. package/dist/index.js.map +1 -1
  8. package/package.json +1 -1
  9. package/dist/cache/index.d.ts +0 -4
  10. package/dist/cache/index.d.ts.map +0 -1
  11. package/dist/cache/invalidation.d.ts +0 -156
  12. package/dist/cache/invalidation.d.ts.map +0 -1
  13. package/dist/cache/kv-cache.d.ts +0 -79
  14. package/dist/cache/kv-cache.d.ts.map +0 -1
  15. package/dist/cache/memory-cache.d.ts +0 -68
  16. package/dist/cache/memory-cache.d.ts.map +0 -1
  17. package/dist/cloudforge/d1-adapter.d.ts +0 -67
  18. package/dist/cloudforge/d1-adapter.d.ts.map +0 -1
  19. package/dist/cloudforge/do-storage.d.ts +0 -51
  20. package/dist/cloudforge/do-storage.d.ts.map +0 -1
  21. package/dist/cloudforge/index.d.ts +0 -4
  22. package/dist/cloudforge/index.d.ts.map +0 -1
  23. package/dist/cloudforge/r2-backup.d.ts +0 -38
  24. package/dist/cloudforge/r2-backup.d.ts.map +0 -1
  25. package/dist/connection/index.d.ts +0 -2
  26. package/dist/connection/index.d.ts.map +0 -1
  27. package/dist/connection/manager.d.ts +0 -54
  28. package/dist/connection/manager.d.ts.map +0 -1
  29. package/dist/index.d.ts.map +0 -1
  30. package/dist/migration/index.d.ts +0 -4
  31. package/dist/migration/index.d.ts.map +0 -1
  32. package/dist/migration/loader.d.ts +0 -88
  33. package/dist/migration/loader.d.ts.map +0 -1
  34. package/dist/migration/runner.d.ts +0 -91
  35. package/dist/migration/runner.d.ts.map +0 -1
  36. package/dist/migration/seeder.d.ts +0 -95
  37. package/dist/migration/seeder.d.ts.map +0 -1
  38. package/dist/query/builder.d.ts +0 -47
  39. package/dist/query/builder.d.ts.map +0 -1
  40. package/dist/query/index.d.ts +0 -3
  41. package/dist/query/index.d.ts.map +0 -1
  42. package/dist/query/raw.d.ts +0 -92
  43. package/dist/query/raw.d.ts.map +0 -1
  44. package/dist/tenant/context.d.ts +0 -52
  45. package/dist/tenant/context.d.ts.map +0 -1
  46. package/dist/tenant/index.d.ts +0 -4
  47. package/dist/tenant/index.d.ts.map +0 -1
  48. package/dist/tenant/query-wrapper.d.ts +0 -96
  49. package/dist/tenant/query-wrapper.d.ts.map +0 -1
  50. package/dist/tenant/schema-manager.d.ts +0 -185
  51. package/dist/tenant/schema-manager.d.ts.map +0 -1
  52. package/dist/transaction/index.d.ts +0 -2
  53. package/dist/transaction/index.d.ts.map +0 -1
  54. package/dist/transaction/transaction.d.ts +0 -51
  55. package/dist/transaction/transaction.d.ts.map +0 -1
  56. package/dist/types/cache.d.ts +0 -214
  57. package/dist/types/cache.d.ts.map +0 -1
  58. package/dist/types/cloudforge.d.ts +0 -753
  59. package/dist/types/cloudforge.d.ts.map +0 -1
  60. package/dist/types/connection.d.ts +0 -91
  61. package/dist/types/connection.d.ts.map +0 -1
  62. package/dist/types/index.d.ts +0 -10
  63. package/dist/types/index.d.ts.map +0 -1
  64. package/dist/types/migration.d.ts +0 -225
  65. package/dist/types/migration.d.ts.map +0 -1
  66. package/dist/types/plugin.d.ts +0 -432
  67. package/dist/types/plugin.d.ts.map +0 -1
  68. package/dist/types/query-builder.d.ts +0 -217
  69. package/dist/types/query-builder.d.ts.map +0 -1
  70. package/dist/types/seed.d.ts +0 -187
  71. package/dist/types/seed.d.ts.map +0 -1
  72. package/dist/types/tenant.d.ts +0 -140
  73. package/dist/types/tenant.d.ts.map +0 -1
  74. package/dist/types/transaction.d.ts +0 -144
  75. package/dist/types/transaction.d.ts.map +0 -1
@@ -1,185 +0,0 @@
1
- import { Result, Logger } from '@gl-life/gl-life-core';
2
- import type { DatabaseConnection, DatabaseConnectionError } from '../types/connection.js';
3
- /**
4
- * Schema manager error types
5
- */
6
- export type SchemaManagerError = {
7
- type: 'INVALID_TENANT_ID';
8
- message: string;
9
- } | {
10
- type: 'INVALID_VERSION';
11
- message: string;
12
- } | {
13
- type: 'SCHEMA_EXISTS';
14
- message: string;
15
- } | {
16
- type: 'SCHEMA_NOT_FOUND';
17
- message: string;
18
- } | {
19
- type: 'MIGRATION_FAILED';
20
- message: string;
21
- cause?: unknown;
22
- } | {
23
- type: 'DATABASE_ERROR';
24
- message: string;
25
- cause?: DatabaseConnectionError;
26
- } | {
27
- type: 'VALIDATION_FAILED';
28
- message: string;
29
- };
30
- /**
31
- * Schema version record
32
- */
33
- export interface SchemaVersion {
34
- version: string;
35
- applied_at: Date;
36
- description?: string;
37
- }
38
- /**
39
- * Schema migration definition
40
- */
41
- export interface SchemaMigration {
42
- version: string;
43
- sql: string;
44
- description?: string;
45
- }
46
- /**
47
- * Schema manager configuration
48
- */
49
- export interface SchemaManagerConfig {
50
- /** Base schema name prefix */
51
- baseSchemaName: string;
52
- /** Table name for tracking schema versions */
53
- schemaVersionTable?: string;
54
- }
55
- /**
56
- * Options for creating tenant schema
57
- */
58
- export interface CreateSchemaOptions {
59
- /** Initial schema version */
60
- version?: string;
61
- /** Whether to use a transaction */
62
- useTransaction?: boolean;
63
- }
64
- /**
65
- * Options for dropping tenant schema
66
- */
67
- export interface DropSchemaOptions {
68
- /** Use CASCADE to drop all objects in schema */
69
- cascade?: boolean;
70
- /** Add IF EXISTS clause */
71
- ifExists?: boolean;
72
- /** Clean up version history */
73
- cleanupVersions?: boolean;
74
- }
75
- /**
76
- * Tenant Schema Manager
77
- *
78
- * Manages per-tenant database schemas for multi-tenant applications.
79
- * Supports schema creation, versioning, migration, and deprovisioning.
80
- *
81
- * Features:
82
- * - Create isolated schemas per tenant
83
- * - Schema versioning and migration tracking
84
- * - Safe schema deprovisioning
85
- * - Transaction support for atomic operations
86
- * - SQL injection prevention via parameterized queries
87
- *
88
- * Usage:
89
- * ```typescript
90
- * const manager = new TenantSchemaManager(connection, logger, {
91
- * baseSchemaName: 'app'
92
- * });
93
- *
94
- * // Provision new tenant
95
- * await manager.createTenantSchema('tenant-123', { version: '1.0.0' });
96
- *
97
- * // Apply migration
98
- * await manager.applyMigration('tenant-123', {
99
- * version: '1.1.0',
100
- * sql: 'ALTER TABLE users ADD COLUMN email VARCHAR(255);'
101
- * });
102
- *
103
- * // Deprovision tenant
104
- * await manager.dropTenantSchema('tenant-123', { cascade: true });
105
- * ```
106
- */
107
- export declare class TenantSchemaManager {
108
- private readonly connection;
109
- private readonly logger;
110
- private readonly config;
111
- constructor(connection: DatabaseConnection, logger: Logger, config: SchemaManagerConfig);
112
- /**
113
- * Create a new tenant schema
114
- *
115
- * @param tenantId - Tenant identifier
116
- * @param options - Schema creation options
117
- * @returns Result with void on success or SchemaManagerError
118
- */
119
- createTenantSchema(tenantId: string, options?: CreateSchemaOptions): Promise<Result<void, SchemaManagerError>>;
120
- /**
121
- * Drop a tenant schema
122
- *
123
- * @param tenantId - Tenant identifier
124
- * @param options - Drop schema options
125
- * @returns Result with void on success or SchemaManagerError
126
- */
127
- dropTenantSchema(tenantId: string, options?: DropSchemaOptions): Promise<Result<void, SchemaManagerError>>;
128
- /**
129
- * Check if tenant schema exists
130
- *
131
- * @param tenantId - Tenant identifier
132
- * @returns Result with boolean indicating existence
133
- */
134
- schemaExists(tenantId: string): Promise<Result<boolean, SchemaManagerError>>;
135
- /**
136
- * Get current schema version for tenant
137
- *
138
- * @param tenantId - Tenant identifier
139
- * @returns Result with version string or null
140
- */
141
- getSchemaVersion(tenantId: string): Promise<Result<string | null, SchemaManagerError>>;
142
- /**
143
- * Update schema version for tenant
144
- *
145
- * @param tenantId - Tenant identifier
146
- * @param version - New version string
147
- * @returns Result with void on success
148
- */
149
- updateSchemaVersion(tenantId: string, version: string): Promise<Result<void, SchemaManagerError>>;
150
- /**
151
- * Get version history for tenant
152
- *
153
- * @param tenantId - Tenant identifier
154
- * @returns Result with array of schema versions
155
- */
156
- getVersionHistory(tenantId: string): Promise<Result<SchemaVersion[], SchemaManagerError>>;
157
- /**
158
- * Apply a migration to tenant schema
159
- *
160
- * @param tenantId - Tenant identifier
161
- * @param migration - Migration definition
162
- * @returns Result with void on success
163
- */
164
- applyMigration(tenantId: string, migration: SchemaMigration): Promise<Result<void, SchemaManagerError>>;
165
- /**
166
- * Get the schema name for a tenant
167
- *
168
- * @param tenantId - Tenant identifier
169
- * @returns Schema name
170
- */
171
- getSchemaName(tenantId: string): string;
172
- /**
173
- * Validate tenant ID format
174
- */
175
- private validateTenantId;
176
- /**
177
- * Validate version format (simple semver check)
178
- */
179
- private isValidVersion;
180
- /**
181
- * Initialize version tracking for new tenant
182
- */
183
- private initializeVersionTracking;
184
- }
185
- //# sourceMappingURL=schema-manager.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"schema-manager.d.ts","sourceRoot":"","sources":["../../src/tenant/schema-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,uBAAuB,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAG3C,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB;IAU7B;;;;;;OAMG;IACG,kBAAkB,CACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAiF5C;;;;;;OAMG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAmD5C;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;IA8BlF;;;;;OAKG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAgC5F;;;;;;OAMG;IACG,mBAAmB,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAiC5C;;;;;OAKG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,kBAAkB,CAAC,CAAC;IA4B/F;;;;;;OAMG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IA4D5C;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IASvC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAKtB;;OAEG;YACW,yBAAyB;CA0BxC"}
@@ -1,2 +0,0 @@
1
- export * from './transaction.js';
2
- //# sourceMappingURL=index.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transaction/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
@@ -1,51 +0,0 @@
1
- import { Result, Logger } from '@gl-life/gl-life-core';
2
- import type { Transaction, TransactionError, TransactionState, TransactionConfig } from '../types/transaction.js';
3
- import type { QueryBuilder } from '../types/query-builder.js';
4
- /**
5
- * Database connection interface
6
- */
7
- interface DbConnection {
8
- execute<T = unknown>(sql: string, params: unknown[]): Promise<T>;
9
- batch?(queries: Array<{
10
- sql: string;
11
- params: unknown[];
12
- }>): Promise<unknown[]>;
13
- }
14
- /**
15
- * Database Transaction implementation
16
- *
17
- * Provides ACID transaction support with:
18
- * - BEGIN/COMMIT/ROLLBACK operations
19
- * - Savepoint support for nested transactions
20
- * - Automatic rollback on errors (configurable)
21
- * - Transaction timeout handling
22
- * - Query builder integration
23
- */
24
- export declare class DatabaseTransaction implements Transaction {
25
- private readonly _id;
26
- private readonly db;
27
- private readonly _logger;
28
- private readonly _config;
29
- private _state;
30
- private startTime;
31
- private timeoutHandle;
32
- constructor(db: DbConnection, logger: Logger, config?: TransactionConfig);
33
- private generateTransactionId;
34
- get id(): string;
35
- get state(): TransactionState;
36
- get config(): TransactionConfig;
37
- get isActive(): boolean;
38
- begin(): Promise<Result<void, TransactionError>>;
39
- commit(): Promise<Result<void, TransactionError>>;
40
- rollback(): Promise<Result<void, TransactionError>>;
41
- savepoint(name: string): Promise<Result<string, TransactionError>>;
42
- rollbackToSavepoint(name: string): Promise<Result<void, TransactionError>>;
43
- releaseSavepoint(name: string): Promise<Result<void, TransactionError>>;
44
- execute<T = unknown>(sql: string, params?: unknown[]): Promise<Result<T, TransactionError>>;
45
- queryBuilder<T = unknown>(table: string): QueryBuilder<T>;
46
- run<T>(callback: (tx: Transaction) => Promise<Result<T, unknown>>): Promise<Result<T, TransactionError>>;
47
- private handleTimeout;
48
- private clearTimeout;
49
- }
50
- export {};
51
- //# sourceMappingURL=transaction.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/transaction/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D;;GAEG;AACH,UAAU,YAAY;IACpB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjE,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAChF;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,aAAa,CAA+B;gBAGlD,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,iBAAsB;IAYhC,OAAO,CAAC,qBAAqB;IAI7B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,KAAK,IAAI,gBAAgB,CAE5B;IAED,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAEK,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAuChD,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAqCjD,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAqCnD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAwBlE,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAwB1E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAwBvE,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,OAAO,EAAO,GACrB,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IA+BvC,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC;IAUnD,GAAG,CAAC,CAAC,EACT,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GACzD,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAiDvC,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,YAAY;CAMrB"}
@@ -1,214 +0,0 @@
1
- import { Result, Option } from '@gl-life/gl-life-core';
2
- /**
3
- * Cache storage backend types
4
- */
5
- export type CacheBackend = 'MEMORY' | 'KV' | 'REDIS' | 'CUSTOM';
6
- /**
7
- * Cache eviction policies
8
- */
9
- export type CacheEvictionPolicy = 'LRU' | 'LFU' | 'FIFO' | 'TTL';
10
- /**
11
- * Cache invalidation strategy
12
- */
13
- export type CacheInvalidationStrategy = 'IMMEDIATE' | 'LAZY' | 'TIME_BASED' | 'MANUAL';
14
- /**
15
- * Cache configuration options
16
- */
17
- export interface CacheConfig {
18
- /** Whether caching is enabled */
19
- enabled: boolean;
20
- /** Cache storage backend */
21
- backend: CacheBackend;
22
- /** Cache eviction policy */
23
- evictionPolicy: CacheEvictionPolicy;
24
- /** Cache invalidation strategy */
25
- invalidationStrategy: CacheInvalidationStrategy;
26
- /** Default TTL in seconds (0 = no expiration) */
27
- defaultTTL: number;
28
- /** Maximum cache size in bytes (0 = unlimited) */
29
- maxSize?: number;
30
- /** Maximum number of cached items (0 = unlimited) */
31
- maxItems?: number;
32
- /** Cache key prefix */
33
- keyPrefix?: string;
34
- /** Whether to cache null/empty results */
35
- cacheNullResults?: boolean;
36
- /** Tables to exclude from caching */
37
- excludedTables?: string[];
38
- /** Custom backend configuration */
39
- backendConfig?: Record<string, unknown>;
40
- }
41
- /**
42
- * Cache entry metadata
43
- */
44
- export interface CacheEntryMetadata {
45
- /** Cache key */
46
- key: string;
47
- /** Entry creation timestamp */
48
- createdAt: Date;
49
- /** Entry last accessed timestamp */
50
- lastAccessedAt: Date;
51
- /** Number of times accessed */
52
- accessCount: number;
53
- /** Entry size in bytes */
54
- size: number;
55
- /** Entry TTL in seconds */
56
- ttl: number;
57
- /** Entry expiration timestamp */
58
- expiresAt?: Date;
59
- }
60
- /**
61
- * Cache entry
62
- */
63
- export interface CacheEntry<T = unknown> {
64
- /** Cached value */
65
- value: T;
66
- /** Entry metadata */
67
- metadata: CacheEntryMetadata;
68
- }
69
- /**
70
- * Cache error types
71
- */
72
- export type CacheError = {
73
- type: 'SET_FAILED';
74
- message: string;
75
- cause?: unknown;
76
- } | {
77
- type: 'GET_FAILED';
78
- message: string;
79
- cause?: unknown;
80
- } | {
81
- type: 'DELETE_FAILED';
82
- message: string;
83
- cause?: unknown;
84
- } | {
85
- type: 'CLEAR_FAILED';
86
- message: string;
87
- cause?: unknown;
88
- } | {
89
- type: 'SIZE_EXCEEDED';
90
- message: string;
91
- maxSize: number;
92
- } | {
93
- type: 'BACKEND_ERROR';
94
- message: string;
95
- cause?: unknown;
96
- } | {
97
- type: 'UNKNOWN';
98
- message: string;
99
- cause?: unknown;
100
- };
101
- /**
102
- * Cache statistics
103
- */
104
- export interface CacheStats {
105
- /** Total number of cached items */
106
- itemCount: number;
107
- /** Total cache size in bytes */
108
- totalSize: number;
109
- /** Cache hit count */
110
- hits: number;
111
- /** Cache miss count */
112
- misses: number;
113
- /** Cache hit rate (0-1) */
114
- hitRate: number;
115
- /** Number of evictions */
116
- evictions: number;
117
- }
118
- /**
119
- * Cache interface
120
- *
121
- * Provides query result caching with configurable backends and eviction policies.
122
- * Supports Cloudflare Workers KV integration for distributed caching.
123
- */
124
- export interface Cache {
125
- /**
126
- * Cache configuration
127
- */
128
- readonly config: CacheConfig;
129
- /**
130
- * Get a value from the cache
131
- *
132
- * @param key - Cache key
133
- * @returns Result with Option containing cached value or CacheError
134
- */
135
- get<T = unknown>(key: string): Promise<Result<Option<T>, CacheError>>;
136
- /**
137
- * Get a value with metadata from the cache
138
- *
139
- * @param key - Cache key
140
- * @returns Result with Option containing cache entry or CacheError
141
- */
142
- getWithMetadata<T = unknown>(key: string): Promise<Result<Option<CacheEntry<T>>, CacheError>>;
143
- /**
144
- * Set a value in the cache
145
- *
146
- * @param key - Cache key
147
- * @param value - Value to cache
148
- * @param ttl - TTL in seconds (optional, uses default if not provided)
149
- * @returns Result with void on success or CacheError on failure
150
- */
151
- set<T = unknown>(key: string, value: T, ttl?: number): Promise<Result<void, CacheError>>;
152
- /**
153
- * Delete a value from the cache
154
- *
155
- * @param key - Cache key
156
- * @returns Result with true if deleted, false if not found
157
- */
158
- delete(key: string): Promise<Result<boolean, CacheError>>;
159
- /**
160
- * Delete multiple values from the cache
161
- *
162
- * @param keys - Array of cache keys
163
- * @returns Result with number of deleted entries
164
- */
165
- deleteMany(keys: string[]): Promise<Result<number, CacheError>>;
166
- /**
167
- * Clear all cached values
168
- *
169
- * @returns Result with void on success or CacheError on failure
170
- */
171
- clear(): Promise<Result<void, CacheError>>;
172
- /**
173
- * Check if a key exists in the cache
174
- *
175
- * @param key - Cache key
176
- * @returns Result with true if key exists
177
- */
178
- has(key: string): Promise<Result<boolean, CacheError>>;
179
- /**
180
- * Invalidate cache entries matching a pattern
181
- *
182
- * @param pattern - Pattern to match (supports wildcards)
183
- * @returns Result with number of invalidated entries
184
- */
185
- invalidate(pattern: string): Promise<Result<number, CacheError>>;
186
- /**
187
- * Invalidate cache entries for a specific table
188
- *
189
- * @param table - Table name
190
- * @returns Result with number of invalidated entries
191
- */
192
- invalidateTable(table: string): Promise<Result<number, CacheError>>;
193
- /**
194
- * Get cache statistics
195
- *
196
- * @returns Result with cache statistics
197
- */
198
- getStats(): Result<CacheStats, CacheError>;
199
- /**
200
- * Reset cache statistics
201
- *
202
- * @returns Result with void on success or CacheError on failure
203
- */
204
- resetStats(): Result<void, CacheError>;
205
- /**
206
- * Generate a cache key for a query
207
- *
208
- * @param sql - SQL query
209
- * @param params - Query parameters
210
- * @returns Cache key string
211
- */
212
- generateKey(sql: string, params?: unknown[]): string;
213
- }
214
- //# sourceMappingURL=cache.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/types/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,IAAI,GACJ,OAAO,GACP,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,WAAW,GACX,MAAM,GACN,YAAY,GACZ,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,4BAA4B;IAC5B,OAAO,EAAE,YAAY,CAAC;IACtB,4BAA4B;IAC5B,cAAc,EAAE,mBAAmB,CAAC;IACpC,kCAAkC;IAClC,oBAAoB,EAAE,yBAAyB,CAAC;IAChD,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qCAAqC;IACrC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,SAAS,EAAE,IAAI,CAAC;IAChB,oCAAoC;IACpC,cAAc,EAAE,IAAI,CAAC;IACrB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,mBAAmB;IACnB,KAAK,EAAE,CAAC,CAAC;IACT,qBAAqB;IACrB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;;OAKG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAEtE;;;;;OAKG;IACH,eAAe,CAAC,CAAC,GAAG,OAAO,EACzB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;IAE1D;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAEhE;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAEpE;;;;OAIG;IACH,QAAQ,IAAI,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAE3C;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAEvC;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;CACtD"}