@plyaz/db 0.0.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.
- package/README.md +169 -0
- package/dist/adapters/drizzle/DrizzleAdapter.d.ts +269 -0
- package/dist/adapters/drizzle/DrizzleAdapter.d.ts.map +1 -0
- package/dist/adapters/index.d.ts +20 -0
- package/dist/adapters/index.d.ts.map +1 -0
- package/dist/adapters/sql/SQLAdapter.d.ts +282 -0
- package/dist/adapters/sql/SQLAdapter.d.ts.map +1 -0
- package/dist/adapters/supabase/SupabaseAdapter.d.ts +305 -0
- package/dist/adapters/supabase/SupabaseAdapter.d.ts.map +1 -0
- package/dist/advanced/backup/BackupService.d.ts +159 -0
- package/dist/advanced/backup/BackupService.d.ts.map +1 -0
- package/dist/advanced/backup/index.d.ts +2 -0
- package/dist/advanced/backup/index.d.ts.map +1 -0
- package/dist/advanced/caching/CacheEvict.decorator.d.ts +3 -0
- package/dist/advanced/caching/CacheEvict.decorator.d.ts.map +1 -0
- package/dist/advanced/caching/Cacheable.decorator.d.ts +99 -0
- package/dist/advanced/caching/Cacheable.decorator.d.ts.map +1 -0
- package/dist/advanced/caching/RedisCache.d.ts +417 -0
- package/dist/advanced/caching/RedisCache.d.ts.map +1 -0
- package/dist/advanced/caching/index.d.ts +4 -0
- package/dist/advanced/caching/index.d.ts.map +1 -0
- package/dist/advanced/connection-pool/DynamicPool.d.ts +234 -0
- package/dist/advanced/connection-pool/DynamicPool.d.ts.map +1 -0
- package/dist/advanced/connection-pool/index.d.ts +2 -0
- package/dist/advanced/connection-pool/index.d.ts.map +1 -0
- package/dist/advanced/index.d.ts +8 -0
- package/dist/advanced/index.d.ts.map +1 -0
- package/dist/advanced/monitoring/AlertManager.d.ts +72 -0
- package/dist/advanced/monitoring/AlertManager.d.ts.map +1 -0
- package/dist/advanced/monitoring/MetricsCollector.d.ts +81 -0
- package/dist/advanced/monitoring/MetricsCollector.d.ts.map +1 -0
- package/dist/advanced/monitoring/index.d.ts +3 -0
- package/dist/advanced/monitoring/index.d.ts.map +1 -0
- package/dist/advanced/multi-tenancy/TenantContext.d.ts +52 -0
- package/dist/advanced/multi-tenancy/TenantContext.d.ts.map +1 -0
- package/dist/advanced/multi-tenancy/TenantRepository.d.ts +292 -0
- package/dist/advanced/multi-tenancy/TenantRepository.d.ts.map +1 -0
- package/dist/advanced/multi-tenancy/index.d.ts +3 -0
- package/dist/advanced/multi-tenancy/index.d.ts.map +1 -0
- package/dist/advanced/read-replica/ReadReplicaAdapter.d.ts +516 -0
- package/dist/advanced/read-replica/ReadReplicaAdapter.d.ts.map +1 -0
- package/dist/advanced/read-replica/ReadReplicaManager.d.ts +68 -0
- package/dist/advanced/read-replica/ReadReplicaManager.d.ts.map +1 -0
- package/dist/advanced/read-replica/UseReplica.decorator.d.ts +24 -0
- package/dist/advanced/read-replica/UseReplica.decorator.d.ts.map +1 -0
- package/dist/advanced/read-replica/index.d.ts +3 -0
- package/dist/advanced/read-replica/index.d.ts.map +1 -0
- package/dist/advanced/sharding/ShardKey.d.ts +80 -0
- package/dist/advanced/sharding/ShardKey.d.ts.map +1 -0
- package/dist/advanced/sharding/ShardRouter.d.ts +66 -0
- package/dist/advanced/sharding/ShardRouter.d.ts.map +1 -0
- package/dist/advanced/sharding/index.d.ts +3 -0
- package/dist/advanced/sharding/index.d.ts.map +1 -0
- package/dist/builder/query/index.d.ts +7 -0
- package/dist/builder/query/index.d.ts.map +1 -0
- package/dist/builder/query/orm.d.ts +22 -0
- package/dist/builder/query/orm.d.ts.map +1 -0
- package/dist/builder/query/sql.d.ts +29 -0
- package/dist/builder/query/sql.d.ts.map +1 -0
- package/dist/extensions/AuditExtension.d.ts +468 -0
- package/dist/extensions/AuditExtension.d.ts.map +1 -0
- package/dist/extensions/CachingAdapter.d.ts +451 -0
- package/dist/extensions/CachingAdapter.d.ts.map +1 -0
- package/dist/extensions/EncryptionExtension.d.ts +95 -0
- package/dist/extensions/EncryptionExtension.d.ts.map +1 -0
- package/dist/extensions/ReadReplicaAdapter.d.ts +32 -0
- package/dist/extensions/ReadReplicaAdapter.d.ts.map +1 -0
- package/dist/extensions/SoftDeleteExtension.d.ts +430 -0
- package/dist/extensions/SoftDeleteExtension.d.ts.map +1 -0
- package/dist/extensions/index.d.ts +79 -0
- package/dist/extensions/index.d.ts.map +1 -0
- package/dist/factory/AdapterFactory.d.ts +111 -0
- package/dist/factory/AdapterFactory.d.ts.map +1 -0
- package/dist/factory/createDatabaseService.d.ts +121 -0
- package/dist/factory/createDatabaseService.d.ts.map +1 -0
- package/dist/index.cjs +8518 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.mjs +8480 -0
- package/dist/index.mjs.map +1 -0
- package/dist/repository/BaseRepository.d.ts +209 -0
- package/dist/repository/BaseRepository.d.ts.map +1 -0
- package/dist/repository/index.d.ts +80 -0
- package/dist/repository/index.d.ts.map +1 -0
- package/dist/security/index.cjs +118 -0
- package/dist/security/index.cjs.map +1 -0
- package/dist/security/index.d.ts +3 -0
- package/dist/security/index.d.ts.map +1 -0
- package/dist/security/index.mjs +114 -0
- package/dist/security/index.mjs.map +1 -0
- package/dist/security/sanitizers/html.sanitizer.d.ts +31 -0
- package/dist/security/sanitizers/html.sanitizer.d.ts.map +1 -0
- package/dist/security/serializers/DataValidation.d.ts +34 -0
- package/dist/security/serializers/DataValidation.d.ts.map +1 -0
- package/dist/service/DatabaseService.d.ts +136 -0
- package/dist/service/DatabaseService.d.ts.map +1 -0
- package/dist/service/EventEmitter.d.ts +110 -0
- package/dist/service/EventEmitter.d.ts.map +1 -0
- package/dist/service/HealthManager.d.ts +166 -0
- package/dist/service/HealthManager.d.ts.map +1 -0
- package/dist/utils/ConfigMerger.d.ts +227 -0
- package/dist/utils/ConfigMerger.d.ts.map +1 -0
- package/dist/utils/databaseResultHelpers.d.ts +98 -0
- package/dist/utils/databaseResultHelpers.d.ts.map +1 -0
- package/dist/utils/index.d.ts +7 -0
- package/dist/utils/index.d.ts.map +1 -0
- package/dist/utils/normalizeDetails.d.ts +111 -0
- package/dist/utils/normalizeDetails.d.ts.map +1 -0
- package/dist/utils/pagination.d.ts +77 -0
- package/dist/utils/pagination.d.ts.map +1 -0
- package/dist/utils/regex.d.ts +199 -0
- package/dist/utils/regex.d.ts.map +1 -0
- package/dist/utils/typeGuards.d.ts +57 -0
- package/dist/utils/typeGuards.d.ts.map +1 -0
- package/dist/utils/validation.d.ts +146 -0
- package/dist/utils/validation.d.ts.map +1 -0
- package/package.json +156 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Database Result Helper Functions for @plyaz/db package
|
|
3
|
+
*
|
|
4
|
+
* This module provides utility functions for creating standardized DatabaseResult objects
|
|
5
|
+
* used throughout the @plyaz/db package. These helpers ensure consistent result formatting
|
|
6
|
+
* across all database operations and adapters.
|
|
7
|
+
*
|
|
8
|
+
* Part of the @plyaz/db package - a TypeScript database abstraction layer with
|
|
9
|
+
* support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
|
|
10
|
+
* soft delete), and advanced features (caching, read replicas, multi-tenancy).
|
|
11
|
+
*
|
|
12
|
+
*/
|
|
13
|
+
import type { DatabaseResult } from "@plyaz/types/db";
|
|
14
|
+
/**
|
|
15
|
+
* Creates a successful DatabaseResult wrapper for operation results
|
|
16
|
+
*
|
|
17
|
+
* Used throughout all database adapters and extensions to wrap successful operation results
|
|
18
|
+
* in a consistent format. This enables standardized error handling and result processing
|
|
19
|
+
* across the entire @plyaz/db package.
|
|
20
|
+
*
|
|
21
|
+
* **Used by:**
|
|
22
|
+
* - All database adapters (DrizzleAdapter, SupabaseAdapter, SQLAdapter)
|
|
23
|
+
* - All extensions (AuditAdapter, EncryptionAdapter, SoftDeleteAdapter, etc.)
|
|
24
|
+
* - DatabaseService for operation results
|
|
25
|
+
* - Repository layer for consistent return types
|
|
26
|
+
*
|
|
27
|
+
* @template T - The type of the successful result value
|
|
28
|
+
* @param {T} value - The successful result value to wrap
|
|
29
|
+
* @returns {DatabaseResult<T>} A success result object with the value
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* ```typescript
|
|
33
|
+
* import { success } from '@plyaz/db/utils';
|
|
34
|
+
*
|
|
35
|
+
* // In adapter methods
|
|
36
|
+
* async findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>> {
|
|
37
|
+
* try {
|
|
38
|
+
* const record = await this.db.select().from(table).where(eq(id));
|
|
39
|
+
* return success(record[0] || null); // Wrap successful result
|
|
40
|
+
* } catch (error) {
|
|
41
|
+
* return failure(new DatabaseError('FIND_FAILED', error.message));
|
|
42
|
+
* }
|
|
43
|
+
* }
|
|
44
|
+
*
|
|
45
|
+
* // In service methods
|
|
46
|
+
* const userResult = await userRepository.findById('user-123');
|
|
47
|
+
* if (userResult.success) {
|
|
48
|
+
* console.log('Found user:', userResult.value.name);
|
|
49
|
+
* }
|
|
50
|
+
* ```
|
|
51
|
+
*
|
|
52
|
+
*/
|
|
53
|
+
export declare function success<T = null>(value?: T): DatabaseResult<T>;
|
|
54
|
+
/**
|
|
55
|
+
* Creates a failed DatabaseResult wrapper for operation errors
|
|
56
|
+
*
|
|
57
|
+
* Used throughout all database adapters and extensions to wrap error results
|
|
58
|
+
* in a consistent format. This enables standardized error handling and result processing
|
|
59
|
+
* across the entire @plyaz/db package.
|
|
60
|
+
*
|
|
61
|
+
* **Used by:**
|
|
62
|
+
* - All database adapters for error cases
|
|
63
|
+
* - All extensions for error propagation
|
|
64
|
+
* - DatabaseService for operation failures
|
|
65
|
+
* - Repository layer for consistent error handling
|
|
66
|
+
*
|
|
67
|
+
* @template T - The type that would have been returned on success
|
|
68
|
+
* @param {Error} error - The error that occurred during the operation
|
|
69
|
+
* @returns {DatabaseResult<T>} A failure result object with the error
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```typescript
|
|
73
|
+
* import { failure } from '@plyaz/db/utils';
|
|
74
|
+
* import { DatabaseError } from '@plyaz/errors';
|
|
75
|
+
import { DATABASE_ERROR_CODES } from '@plyaz/types/errors';
|
|
76
|
+
*
|
|
77
|
+
* // In adapter methods
|
|
78
|
+
* async create<T>(table: string, data: T): Promise<DatabaseResult<T>> {
|
|
79
|
+
* try {
|
|
80
|
+
* const result = await this.db.insert(table).values(data).returning();
|
|
81
|
+
* return success(result[0]);
|
|
82
|
+
* } catch (error) {
|
|
83
|
+
* return failure(new DatabaseError(
|
|
84
|
+
* `Failed to create record: ${error.message}`));
|
|
85
|
+
* }
|
|
86
|
+
* }
|
|
87
|
+
*
|
|
88
|
+
* // In service layer error handling
|
|
89
|
+
* const createResult = await userRepository.create(userData);
|
|
90
|
+
* if (!createResult.success) {
|
|
91
|
+
* logger.error('User creation failed:', createResult.error.message);
|
|
92
|
+
* throw createResult.error;
|
|
93
|
+
* }
|
|
94
|
+
* ```
|
|
95
|
+
*
|
|
96
|
+
*/
|
|
97
|
+
export declare function failure<T>(error: Error): DatabaseResult<T>;
|
|
98
|
+
//# sourceMappingURL=databaseResultHelpers.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"databaseResultHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/databaseResultHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,GAAE,CAAa,GAAG,cAAc,CAAC,CAAC,CAAC,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,CAE1D"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Detail Normalization Utilities for @plyaz/db package
|
|
3
|
+
*
|
|
4
|
+
* This module provides utilities for normalizing various data types into consistent
|
|
5
|
+
* string-based record formats. Used throughout the @plyaz/db package for standardizing
|
|
6
|
+
* error details, health status information, and event metadata.
|
|
7
|
+
*
|
|
8
|
+
* Part of the @plyaz/db package - a TypeScript database abstraction layer with
|
|
9
|
+
* support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
|
|
10
|
+
* soft delete), and advanced features (caching, read replicas, multi-tenancy).
|
|
11
|
+
*
|
|
12
|
+
*/
|
|
13
|
+
/**
|
|
14
|
+
* Normalizes any input into a standardized Record<string, string> format
|
|
15
|
+
*
|
|
16
|
+
* Converts various data types into a consistent string-based record format
|
|
17
|
+
* for use in error details, health status information, and event metadata.
|
|
18
|
+
* Provides safe handling of different input types with fallback strategies.
|
|
19
|
+
*
|
|
20
|
+
* **Normalization Rules:**
|
|
21
|
+
* - Objects: Converts all property values to strings while preserving keys
|
|
22
|
+
* - Primitives: Wraps in { info: stringValue } format
|
|
23
|
+
* - null/undefined: Returns undefined (no details)
|
|
24
|
+
* - Arrays: Converts to { info: stringified array }
|
|
25
|
+
* - Errors: Safely handles conversion failures
|
|
26
|
+
*
|
|
27
|
+
* **Used by:**
|
|
28
|
+
* - HealthManager for health status details
|
|
29
|
+
* - DatabaseEventEmitter for event metadata
|
|
30
|
+
* - Error handling throughout adapter chain
|
|
31
|
+
* - Audit logging for consistent detail formatting
|
|
32
|
+
*
|
|
33
|
+
* @param {unknown} details - Input details of any type to normalize
|
|
34
|
+
* @returns {Record<string, string> | undefined} Normalized details as string record or undefined
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* ```typescript
|
|
38
|
+
* import { normalizeDetails } from '@plyaz/db/utils';
|
|
39
|
+
*
|
|
40
|
+
* // Object normalization
|
|
41
|
+
* const objDetails = normalizeDetails({
|
|
42
|
+
* count: 42,
|
|
43
|
+
* active: true,
|
|
44
|
+
* name: 'test'
|
|
45
|
+
* });
|
|
46
|
+
* console.log(objDetails);
|
|
47
|
+
* // { count: "42", active: "true", name: "test" }
|
|
48
|
+
*
|
|
49
|
+
* // Primitive normalization
|
|
50
|
+
* const stringDetails = normalizeDetails("Connection timeout");
|
|
51
|
+
* console.log(stringDetails);
|
|
52
|
+
* // { info: "Connection timeout" }
|
|
53
|
+
*
|
|
54
|
+
* // Number normalization
|
|
55
|
+
* const numberDetails = normalizeDetails(404);
|
|
56
|
+
* console.log(numberDetails);
|
|
57
|
+
* // { info: "404" }
|
|
58
|
+
*
|
|
59
|
+
* // Null/undefined handling
|
|
60
|
+
* const nullDetails = normalizeDetails(null);
|
|
61
|
+
* console.log(nullDetails);
|
|
62
|
+
* // undefined
|
|
63
|
+
*
|
|
64
|
+
* // Array normalization
|
|
65
|
+
* const arrayDetails = normalizeDetails(['error1', 'error2']);
|
|
66
|
+
* console.log(arrayDetails);
|
|
67
|
+
* // { info: "error1,error2" }
|
|
68
|
+
*
|
|
69
|
+
* // Error object normalization
|
|
70
|
+
* const errorDetails = normalizeDetails(new Error('Database error'));
|
|
71
|
+
* console.log(errorDetails);
|
|
72
|
+
* // { info: "Error: Database error" }
|
|
73
|
+
* ```
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* ### Usage in Health Status
|
|
77
|
+
* ```typescript
|
|
78
|
+
* // In HealthManager.checkHealth()
|
|
79
|
+
* const healthStatus = {
|
|
80
|
+
* isHealthy: true,
|
|
81
|
+
* responseTime: 150,
|
|
82
|
+
* details: normalizeDetails({
|
|
83
|
+
* adapter: 'drizzle',
|
|
84
|
+
* connections: 5,
|
|
85
|
+
* lastQuery: new Date()
|
|
86
|
+
* })
|
|
87
|
+
* };
|
|
88
|
+
* // details: { adapter: "drizzle", connections: "5", lastQuery: "2024-01-01T10:00:00.000Z" }
|
|
89
|
+
* ```
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* ### Usage in Error Handling
|
|
93
|
+
* ```typescript
|
|
94
|
+
* // In adapter error handling
|
|
95
|
+
* catch (error) {
|
|
96
|
+
* return failure(new DatabaseError(
|
|
97
|
+
* 'QUERY_FAILED',
|
|
98
|
+
* HTTP_STATUS.INTERNAL_SERVER_ERROR,
|
|
99
|
+
* 'Query execution failed',
|
|
100
|
+
* normalizeDetails({
|
|
101
|
+
* query: sql,
|
|
102
|
+
* params: queryParams,
|
|
103
|
+
* originalError: error.message
|
|
104
|
+
* })
|
|
105
|
+
* ));
|
|
106
|
+
* }
|
|
107
|
+
* ```
|
|
108
|
+
*
|
|
109
|
+
*/
|
|
110
|
+
export declare function normalizeDetails(details: unknown): Record<string, string> | undefined;
|
|
111
|
+
//# sourceMappingURL=normalizeDetails.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"normalizeDetails.d.ts","sourceRoot":"","sources":["../../src/utils/normalizeDetails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CA8BpC"}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Pagination Utilities for @plyaz/db package
|
|
3
|
+
*
|
|
4
|
+
* This module provides pagination calculation utilities used across all database adapters
|
|
5
|
+
* to generate consistent pagination metadata for query results. Supports offset-based
|
|
6
|
+
* pagination with page calculation and validation.
|
|
7
|
+
*
|
|
8
|
+
* Part of the @plyaz/db package - a TypeScript database abstraction layer with
|
|
9
|
+
* support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
|
|
10
|
+
* soft delete), and advanced features (caching, read replicas, multi-tenancy).
|
|
11
|
+
*
|
|
12
|
+
* @module pagination
|
|
13
|
+
*/
|
|
14
|
+
import type { PaginationInfo, PaginationOptions } from "@plyaz/types";
|
|
15
|
+
/**
|
|
16
|
+
* Calculates comprehensive pagination metadata for database query results
|
|
17
|
+
*
|
|
18
|
+
* Generates pagination information used by all database adapters to provide
|
|
19
|
+
* consistent pagination metadata in query results. Supports both paginated
|
|
20
|
+
* and non-paginated queries with automatic page calculation.
|
|
21
|
+
*
|
|
22
|
+
* **Used by:**
|
|
23
|
+
* - DrizzleAdapter.findMany() for ORM-based pagination
|
|
24
|
+
* - SupabaseAdapter.findMany() for Supabase pagination
|
|
25
|
+
* - SQLAdapter.findMany() for raw SQL pagination
|
|
26
|
+
* - All repository methods that return paginated results
|
|
27
|
+
*
|
|
28
|
+
* **Calculation Logic:**
|
|
29
|
+
* - Page numbers are 1-based (first page = 1)
|
|
30
|
+
* - Current page = floor(offset / limit) + 1
|
|
31
|
+
* - Total pages = ceil(total / limit)
|
|
32
|
+
* - Handles edge cases (no limit, empty results, etc.)
|
|
33
|
+
*
|
|
34
|
+
* @param {number} total - Total number of items matching the query
|
|
35
|
+
* @param {PaginationOptions} [options] - Optional pagination configuration
|
|
36
|
+
* @param {number} [options.limit] - Maximum items per page
|
|
37
|
+
* @param {number} [options.offset] - Number of items to skip (default: 0)
|
|
38
|
+
* @returns {PaginationInfo} Complete pagination metadata object
|
|
39
|
+
*
|
|
40
|
+
* @example
|
|
41
|
+
* ```typescript
|
|
42
|
+
* import { calculatePagination } from '@plyaz/db/utils';
|
|
43
|
+
*
|
|
44
|
+
* // Standard pagination (page 2 of 20 items per page)
|
|
45
|
+
* const pagination1 = calculatePagination(100, { limit: 20, offset: 20 });
|
|
46
|
+
* console.log(pagination1);
|
|
47
|
+
* // {
|
|
48
|
+
* // page: 2,
|
|
49
|
+
* // limit: 20,
|
|
50
|
+
* // offset: 20,
|
|
51
|
+
* // totalPages: 5
|
|
52
|
+
* // }
|
|
53
|
+
*
|
|
54
|
+
* // First page
|
|
55
|
+
* const pagination2 = calculatePagination(100, { limit: 20, offset: 0 });
|
|
56
|
+
* console.log(pagination2);
|
|
57
|
+
* // {
|
|
58
|
+
* // page: 1,
|
|
59
|
+
* // limit: 20,
|
|
60
|
+
* // offset: 0,
|
|
61
|
+
* // totalPages: 5
|
|
62
|
+
* // }
|
|
63
|
+
*
|
|
64
|
+
* // No pagination (return all results)
|
|
65
|
+
* const pagination3 = calculatePagination(100);
|
|
66
|
+
* console.log(pagination3);
|
|
67
|
+
* // {
|
|
68
|
+
* // page: undefined,
|
|
69
|
+
* // limit: undefined,
|
|
70
|
+
* // offset: 0,
|
|
71
|
+
* // totalPages: undefined
|
|
72
|
+
* // }
|
|
73
|
+
* ```
|
|
74
|
+
*
|
|
75
|
+
*/
|
|
76
|
+
export declare function calculatePagination(total: number, options?: PaginationOptions): PaginationInfo;
|
|
77
|
+
//# sourceMappingURL=pagination.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAiFtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAyBhB"}
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Centralized Regex Patterns for @plyaz/db package
|
|
3
|
+
*
|
|
4
|
+
* This module contains all regex patterns used throughout the database package.
|
|
5
|
+
* Centralizing regex patterns improves maintainability, reusability, and consistency.
|
|
6
|
+
*
|
|
7
|
+
* Part of the @plyaz/db package - a TypeScript database abstraction layer with
|
|
8
|
+
* support for multiple adapters (Drizzle, Supabase, SQL), extensions (audit, encryption,
|
|
9
|
+
* soft delete), and advanced features (caching, read replicas, multi-tenancy).
|
|
10
|
+
*
|
|
11
|
+
*/
|
|
12
|
+
/**
|
|
13
|
+
* Database field and table name validation patterns
|
|
14
|
+
* Used for SQL injection prevention and database identifier validation
|
|
15
|
+
*/
|
|
16
|
+
export declare const DATABASE_PATTERNS: {
|
|
17
|
+
/**
|
|
18
|
+
* Validates database field names (columns)
|
|
19
|
+
* - Must start with letter (a-z, A-Z) or underscore (_)
|
|
20
|
+
* - Can contain letters, numbers, and underscores
|
|
21
|
+
* - Prevents SQL injection through field names
|
|
22
|
+
*
|
|
23
|
+
* Used in: validation.ts, sql.ts, DrizzleAdapter.ts, SQLAdapter.ts
|
|
24
|
+
*/
|
|
25
|
+
readonly FIELD_NAME: RegExp;
|
|
26
|
+
/**
|
|
27
|
+
* Validates database table names
|
|
28
|
+
* - Same rules as field names for consistency
|
|
29
|
+
* - Follows SQL identifier naming conventions
|
|
30
|
+
*
|
|
31
|
+
* Used in: validation.ts, CacheEvict.decorator.ts
|
|
32
|
+
*/
|
|
33
|
+
readonly TABLE_NAME: RegExp;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Cache key validation patterns
|
|
37
|
+
* Used for validating cache keys and patterns in caching system
|
|
38
|
+
*/
|
|
39
|
+
export declare const CACHE_PATTERNS: {
|
|
40
|
+
/**
|
|
41
|
+
* Validates cache keys
|
|
42
|
+
* - Allows letters, numbers, colons, underscores, and hyphens
|
|
43
|
+
* - Used for Redis cache key validation
|
|
44
|
+
*
|
|
45
|
+
* Used in: CacheEvict.decorator.ts
|
|
46
|
+
*/
|
|
47
|
+
readonly CACHE_KEY: RegExp;
|
|
48
|
+
/**
|
|
49
|
+
* Validates cache patterns (with wildcards)
|
|
50
|
+
* - Same as cache key but allows asterisk (*) for wildcards
|
|
51
|
+
* - Used for cache pattern matching and eviction
|
|
52
|
+
*
|
|
53
|
+
* Used in: CacheEvict.decorator.ts
|
|
54
|
+
*/
|
|
55
|
+
readonly CACHE_PATTERN: RegExp;
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* SQL query sanitization patterns
|
|
59
|
+
* Used for cleaning and normalizing SQL queries for metrics and logging
|
|
60
|
+
*/
|
|
61
|
+
export declare const SQL_PATTERNS: {
|
|
62
|
+
/**
|
|
63
|
+
* Matches PostgreSQL parameter placeholders ($1, $2, etc.)
|
|
64
|
+
* - Used to normalize parameterized queries for metrics
|
|
65
|
+
*
|
|
66
|
+
* Used in: MetricsCollector.ts
|
|
67
|
+
*/
|
|
68
|
+
readonly POSTGRES_PARAMS: RegExp;
|
|
69
|
+
/**
|
|
70
|
+
* Matches numeric values in SQL queries
|
|
71
|
+
* - Used to replace numbers with placeholders for query normalization
|
|
72
|
+
*
|
|
73
|
+
* Used in: MetricsCollector.ts
|
|
74
|
+
*/
|
|
75
|
+
readonly NUMERIC_VALUES: RegExp;
|
|
76
|
+
/**
|
|
77
|
+
* Matches string literals in SQL queries (single quotes)
|
|
78
|
+
* - Used to replace string values with placeholders
|
|
79
|
+
*
|
|
80
|
+
* Used in: MetricsCollector.ts
|
|
81
|
+
*/
|
|
82
|
+
readonly STRING_LITERALS: RegExp;
|
|
83
|
+
};
|
|
84
|
+
/**
|
|
85
|
+
* Input sanitization patterns
|
|
86
|
+
* Used for cleaning user input and preventing injection attacks
|
|
87
|
+
*/
|
|
88
|
+
export declare const SANITIZATION_PATTERNS: {
|
|
89
|
+
/**
|
|
90
|
+
* Matches dangerous characters for SQL injection prevention
|
|
91
|
+
* - Null byte, backspace, tab, newline, carriage return
|
|
92
|
+
* - Single and double quotes, backslashes, percent signs
|
|
93
|
+
*
|
|
94
|
+
* Used in: validation.ts (sanitizeInput function)
|
|
95
|
+
*/
|
|
96
|
+
readonly DANGEROUS_CHARS: RegExp;
|
|
97
|
+
/**
|
|
98
|
+
* Matches shell metacharacters for command injection prevention
|
|
99
|
+
* - Semicolon, ampersand, pipe, backtick, dollar, parentheses, etc.
|
|
100
|
+
*
|
|
101
|
+
* Used in: BackupService.ts (sanitizeCommand function)
|
|
102
|
+
*/
|
|
103
|
+
readonly SHELL_METACHARACTERS: RegExp;
|
|
104
|
+
/**
|
|
105
|
+
* Matches multiple whitespace characters
|
|
106
|
+
* - Used to normalize whitespace in sanitized input
|
|
107
|
+
*
|
|
108
|
+
* Used in: BackupService.ts
|
|
109
|
+
*/
|
|
110
|
+
readonly MULTIPLE_WHITESPACE: RegExp;
|
|
111
|
+
/**
|
|
112
|
+
* Matches line breaks and tabs
|
|
113
|
+
* - Used to replace line breaks with spaces
|
|
114
|
+
*
|
|
115
|
+
* Used in: BackupService.ts
|
|
116
|
+
*/
|
|
117
|
+
readonly LINE_BREAKS_TABS: RegExp;
|
|
118
|
+
/**
|
|
119
|
+
* Matches Unicode control characters
|
|
120
|
+
* - Uses Unicode property escape to match all control characters
|
|
121
|
+
*
|
|
122
|
+
* Used in: BackupService.ts
|
|
123
|
+
*/
|
|
124
|
+
readonly CONTROL_CHARACTERS: RegExp;
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* File and path patterns
|
|
128
|
+
* Used for file operations and path validation
|
|
129
|
+
*/
|
|
130
|
+
export declare const FILE_PATTERNS: {
|
|
131
|
+
/**
|
|
132
|
+
* Matches colon and dot characters in timestamps
|
|
133
|
+
* - Used to create filesystem-safe timestamps
|
|
134
|
+
*
|
|
135
|
+
* Used in: BackupService.ts (timestamp generation)
|
|
136
|
+
*/
|
|
137
|
+
readonly TIMESTAMP_CHARS: RegExp;
|
|
138
|
+
};
|
|
139
|
+
/**
|
|
140
|
+
* Utility functions for common regex operations
|
|
141
|
+
*/
|
|
142
|
+
export declare const DB_REGEX: {
|
|
143
|
+
/**
|
|
144
|
+
* Tests if a string matches the database field name pattern
|
|
145
|
+
* @param fieldName - The field name to validate
|
|
146
|
+
* @returns True if valid database field name
|
|
147
|
+
*/
|
|
148
|
+
readonly isValidFieldName: (fieldName: string) => boolean;
|
|
149
|
+
/**
|
|
150
|
+
* Tests if a string matches the database table name pattern
|
|
151
|
+
* @param tableName - The table name to validate
|
|
152
|
+
* @returns True if valid database table name
|
|
153
|
+
*/
|
|
154
|
+
readonly isValidTableName: (tableName: string) => boolean;
|
|
155
|
+
/**
|
|
156
|
+
* Tests if a string matches the cache key pattern
|
|
157
|
+
* @param cacheKey - The cache key to validate
|
|
158
|
+
* @returns True if valid cache key
|
|
159
|
+
*/
|
|
160
|
+
readonly isValidCacheKey: (cacheKey: string) => boolean;
|
|
161
|
+
/**
|
|
162
|
+
* Tests if a string matches the cache pattern (with wildcards)
|
|
163
|
+
* @param cachePattern - The cache pattern to validate
|
|
164
|
+
* @returns True if valid cache pattern
|
|
165
|
+
*/
|
|
166
|
+
readonly isValidCachePattern: (cachePattern: string) => boolean;
|
|
167
|
+
/**
|
|
168
|
+
* Normalizes SQL query by replacing parameters and values with placeholders
|
|
169
|
+
* @param query - The SQL query to normalize
|
|
170
|
+
* @returns Normalized query string
|
|
171
|
+
*/
|
|
172
|
+
readonly normalizeSqlQuery: (query: string) => string;
|
|
173
|
+
/**
|
|
174
|
+
* Sanitizes input by escaping dangerous characters
|
|
175
|
+
* @param input - The input string to sanitize
|
|
176
|
+
* @param escapeMap - Map of characters to their escaped equivalents
|
|
177
|
+
* @returns Sanitized string
|
|
178
|
+
*/
|
|
179
|
+
readonly sanitizeDangerousChars: (input: string, escapeMap: Record<string, string>) => string;
|
|
180
|
+
/**
|
|
181
|
+
* Creates filesystem-safe timestamp string
|
|
182
|
+
* @param timestamp - ISO timestamp string
|
|
183
|
+
* @returns Filesystem-safe timestamp
|
|
184
|
+
*/
|
|
185
|
+
readonly createSafeTimestamp: (timestamp: string) => string;
|
|
186
|
+
/**
|
|
187
|
+
* Sanitizes command string by removing shell metacharacters
|
|
188
|
+
* @param command - Command string to sanitize
|
|
189
|
+
* @returns Sanitized command string
|
|
190
|
+
*/
|
|
191
|
+
readonly sanitizeCommand: (command: string) => string;
|
|
192
|
+
/**
|
|
193
|
+
* Sanitizes log message by normalizing whitespace and removing control characters
|
|
194
|
+
* @param message - Log message to sanitize
|
|
195
|
+
* @returns Sanitized log message
|
|
196
|
+
*/
|
|
197
|
+
readonly sanitizeLogMessage: (message: string) => string;
|
|
198
|
+
};
|
|
199
|
+
//# sourceMappingURL=regex.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"regex.d.ts","sourceRoot":"","sources":["../../src/utils/regex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;;;;OAOG;;IAGH;;;;;;OAMG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;;;OAMG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB;;;;;OAKG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;OAIG;2CAC2B,MAAM,KAAG,OAAO;IAI9C;;;;OAIG;2CAC2B,MAAM,KAAG,OAAO;IAI9C;;;;OAIG;yCACyB,MAAM,KAAG,OAAO;IAI5C;;;;OAIG;iDACiC,MAAM,KAAG,OAAO;IAIpD;;;;OAIG;wCACwB,MAAM,KAAG,MAAM;IAO1C;;;;;OAKG;6CAEM,MAAM,aACF,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAChC,MAAM;IAOT;;;;OAIG;8CAC8B,MAAM,KAAG,MAAM;IAIhD;;;;OAIG;wCACwB,MAAM,KAAG,MAAM;IAO1C;;;;OAIG;2CAC2B,MAAM,KAAG,MAAM;CAMrC,CAAC"}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Type Guard Utilities for @plyaz/db package
|
|
3
|
+
*
|
|
4
|
+
* This module provides type guard functions for runtime type checking throughout
|
|
5
|
+
* the @plyaz/db package. These utilities replace direct typeof checks with
|
|
6
|
+
* consistent, reusable type validation functions.
|
|
7
|
+
*
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Type guard to check if a value is a string
|
|
11
|
+
*
|
|
12
|
+
* @param {unknown} value - The value to check
|
|
13
|
+
* @returns {value is string} True if value is a string, false otherwise
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```typescript
|
|
17
|
+
* import { isString } from '@plyaz/db/utils';
|
|
18
|
+
*
|
|
19
|
+
* if (isString(userInput)) {
|
|
20
|
+
* // userInput is now typed as string
|
|
21
|
+
* console.log(userInput.toLowerCase());
|
|
22
|
+
* }
|
|
23
|
+
* ```
|
|
24
|
+
*/
|
|
25
|
+
export declare function isString(value: unknown): value is string;
|
|
26
|
+
/**
|
|
27
|
+
* Type guard to check if a value is a non-empty string
|
|
28
|
+
*
|
|
29
|
+
* @param {unknown} value - The value to check
|
|
30
|
+
* @returns {value is string} True if value is a non-empty string, false otherwise
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* ```typescript
|
|
34
|
+
* import { isNonEmptyString } from '@plyaz/db/utils';
|
|
35
|
+
*
|
|
36
|
+
* if (isNonEmptyString(tableName)) {
|
|
37
|
+
* // tableName is guaranteed to be a non-empty string
|
|
38
|
+
* const query = `SELECT * FROM ${tableName}`;
|
|
39
|
+
* }
|
|
40
|
+
* ```
|
|
41
|
+
*/
|
|
42
|
+
export declare function isNonEmptyString(value: unknown): value is string;
|
|
43
|
+
/**
|
|
44
|
+
* Type guard to check if a value is a number
|
|
45
|
+
*
|
|
46
|
+
* @param {unknown} value - The value to check
|
|
47
|
+
* @returns {value is number} True if value is a number, false otherwise
|
|
48
|
+
*/
|
|
49
|
+
export declare function isNumber(value: unknown): value is number;
|
|
50
|
+
/**
|
|
51
|
+
* Type guard to check if a value is an object (not null, not array)
|
|
52
|
+
*
|
|
53
|
+
* @param {unknown} value - The value to check
|
|
54
|
+
* @returns {value is object} True if value is an object, false otherwise
|
|
55
|
+
*/
|
|
56
|
+
export declare function isObject(value: unknown): value is object;
|
|
57
|
+
//# sourceMappingURL=typeGuards.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD"}
|