@earth-app/collegedb 1.0.1 → 1.0.2
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 +1457 -25
- package/dist/durable.d.ts +12 -2
- package/dist/durable.d.ts.map +1 -1
- package/dist/errors.d.ts +52 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -7
- package/dist/index.js.map +9 -8
- package/dist/kvmap.d.ts.map +1 -1
- package/dist/migrations.d.ts +14 -0
- package/dist/migrations.d.ts.map +1 -1
- package/dist/router.d.ts +38 -3
- package/dist/router.d.ts.map +1 -1
- package/dist/types.d.ts +48 -4
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -2
package/dist/kvmap.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"kvmap.d.ts","sourceRoot":"","sources":["../src/kvmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"kvmap.d.ts","sourceRoot":"","sources":["../src/kvmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAa;IAKb,OAAO,CAAC,EAAE;IAJtB;;;OAGG;gBACiB,EAAE,EAAE,WAAW;IAEnC;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAMvE;;;;;;;;;;;;;;;;OAgBG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB7E;;;;;;;;;;;;;;;;;OAiBG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D;;;;;;;;;;;;;OAaG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKzC;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD;;;;;;;;;;;;;OAaG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjD;;;;;;;;;;;;;;OAcG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAcvD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAc1D;;;;;;;;;;;;;;;;;;;OAmBG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;CAKvC"}
|
package/dist/migrations.d.ts
CHANGED
|
@@ -389,4 +389,18 @@ export declare function checkMigrationNeeded(d1: D1Database, shardName: string,
|
|
|
389
389
|
* ```
|
|
390
390
|
*/
|
|
391
391
|
export declare function clearMigrationCache(): void;
|
|
392
|
+
/**
|
|
393
|
+
* Clears a specific migration cache entry
|
|
394
|
+
*
|
|
395
|
+
* Resets the cache for a specific shard, forcing re-check on next
|
|
396
|
+
* migration detection call.
|
|
397
|
+
*
|
|
398
|
+
* @param shardName - The shard name to clear from cache
|
|
399
|
+
* @example
|
|
400
|
+
* ```typescript
|
|
401
|
+
* // Force re-check of specific shard
|
|
402
|
+
* clearShardMigrationCache('db-auto');
|
|
403
|
+
* ```
|
|
404
|
+
*/
|
|
405
|
+
export declare function clearShardMigrationCache(shardName: string): void;
|
|
392
406
|
//# sourceMappingURL=migrations.d.ts.map
|
package/dist/migrations.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"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"}
|
package/dist/router.d.ts
CHANGED
|
@@ -39,8 +39,8 @@
|
|
|
39
39
|
* @author CollegeDB Team
|
|
40
40
|
* @since 1.0.0
|
|
41
41
|
*/
|
|
42
|
-
import type { D1Database, D1PreparedStatement, D1Result } from '@cloudflare/workers-types';
|
|
43
|
-
import type { CollegeDBConfig, ShardStats } from './types.js';
|
|
42
|
+
import type { D1Database, D1PreparedStatement, D1Result, Request } from '@cloudflare/workers-types';
|
|
43
|
+
import type { CollegeDBConfig, D1Region, ShardStats } from './types.js';
|
|
44
44
|
/**
|
|
45
45
|
* Sets up the global configuration for the CollegeDB system. This must be called
|
|
46
46
|
* before any other operations can be performed. The configuration includes KV
|
|
@@ -144,6 +144,41 @@ export declare function initializeAsync(config: CollegeDBConfig): Promise<void>;
|
|
|
144
144
|
* ```
|
|
145
145
|
*/
|
|
146
146
|
export declare function collegedb<T>(config: CollegeDBConfig, callback: () => T): Promise<T>;
|
|
147
|
+
/**
|
|
148
|
+
* Resets the global configuration (for testing purposes only)
|
|
149
|
+
*
|
|
150
|
+
* @private
|
|
151
|
+
* @internal
|
|
152
|
+
*/
|
|
153
|
+
export declare function resetConfig(): void;
|
|
154
|
+
/**
|
|
155
|
+
* Determines the closest D1 region based on an IP address.
|
|
156
|
+
* Uses IP geolocation to estimate the user's location and find the nearest D1 region.
|
|
157
|
+
*
|
|
158
|
+
* This function uses Cloudflare's CF object which provides geolocation data
|
|
159
|
+
* in Cloudflare Workers environment. Falls back to 'wnam' if geolocation fails.
|
|
160
|
+
*
|
|
161
|
+
* @param request - The incoming Request object (contains CF geolocation data in Cloudflare Workers)
|
|
162
|
+
* @returns The closest D1Region based on IP geolocation
|
|
163
|
+
* @example
|
|
164
|
+
* ```typescript
|
|
165
|
+
* // In a Cloudflare Worker
|
|
166
|
+
* export default {
|
|
167
|
+
* async fetch(request: Request, env: Env) {
|
|
168
|
+
* const userRegion = getClosestRegionFromIP(request);
|
|
169
|
+
*
|
|
170
|
+
* initialize({
|
|
171
|
+
* kv: env.KV,
|
|
172
|
+
* strategy: 'location',
|
|
173
|
+
* targetRegion: userRegion, // Automatically optimized for user location
|
|
174
|
+
* shardLocations: { ... },
|
|
175
|
+
* shards: { ... }
|
|
176
|
+
* });
|
|
177
|
+
* }
|
|
178
|
+
* };
|
|
179
|
+
* ```
|
|
180
|
+
*/
|
|
181
|
+
export declare function getClosestRegionFromIP(request: Request): D1Region;
|
|
147
182
|
/**
|
|
148
183
|
* Creates the database schema in the specified D1 database
|
|
149
184
|
*
|
|
@@ -165,7 +200,7 @@ export declare function collegedb<T>(config: CollegeDBConfig, callback: () => T)
|
|
|
165
200
|
*/
|
|
166
201
|
export declare function createSchema(d1: D1Database, schema: string): Promise<void>;
|
|
167
202
|
/**
|
|
168
|
-
* Prepares a SQL statement for execution.
|
|
203
|
+
* Prepares a SQL statement for execution with operation-aware routing.
|
|
169
204
|
*
|
|
170
205
|
* @param key - The primary key to route the query
|
|
171
206
|
* @param sql - The SQL statement to prepare
|
package/dist/router.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;
|
|
1
|
+
{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}
|
package/dist/types.d.ts
CHANGED
|
@@ -26,13 +26,42 @@
|
|
|
26
26
|
* @since 1.0.0
|
|
27
27
|
*/
|
|
28
28
|
import type { D1Database, DurableObjectNamespace, KVNamespace } from '@cloudflare/workers-types';
|
|
29
|
+
/**
|
|
30
|
+
* Available Cloudflare D1 regions for geographic optimization
|
|
31
|
+
*/
|
|
32
|
+
export type D1Region = 'wnam' | 'enam' | 'weur' | 'eeur' | 'apac' | 'oc' | 'me' | 'af';
|
|
33
|
+
/**
|
|
34
|
+
* Shard location configuration for geographic optimization
|
|
35
|
+
*/
|
|
36
|
+
export interface ShardLocation {
|
|
37
|
+
/** The D1 region where this shard is located */
|
|
38
|
+
region: D1Region;
|
|
39
|
+
/** Optional priority weight for this shard (higher = preferred) */
|
|
40
|
+
priority?: number;
|
|
41
|
+
}
|
|
29
42
|
/**
|
|
30
43
|
* Sharding strategy options for CollegeDB
|
|
31
44
|
* - `round-robin`: Distributes keys evenly across available shards.
|
|
32
45
|
* - `random`: Selects a random shard for each key.
|
|
33
46
|
* - `hash`: Uses a hash function to determine the shard based on the primary key.
|
|
47
|
+
* - `location`: Selects shards based on geographic proximity to reduce latency.
|
|
48
|
+
*/
|
|
49
|
+
export type ShardingStrategy = 'round-robin' | 'random' | 'hash' | 'location';
|
|
50
|
+
/**
|
|
51
|
+
* Mixed sharding strategy configuration for different operation types
|
|
52
|
+
* @since 1.0.2
|
|
53
|
+
*/
|
|
54
|
+
export interface MixedShardingStrategy {
|
|
55
|
+
/** Strategy for read operations (SELECT) */
|
|
56
|
+
read: ShardingStrategy;
|
|
57
|
+
/** Strategy for write operations (INSERT, UPDATE, DELETE) */
|
|
58
|
+
write: ShardingStrategy;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Database operation types for strategy selection
|
|
62
|
+
* @since 1.0.2
|
|
34
63
|
*/
|
|
35
|
-
export type
|
|
64
|
+
export type OperationType = 'read' | 'write';
|
|
36
65
|
/**
|
|
37
66
|
* Environment bindings for the Cloudflare Worker
|
|
38
67
|
*/
|
|
@@ -54,8 +83,17 @@ export interface CollegeDBConfig {
|
|
|
54
83
|
coordinator?: DurableObjectNamespace;
|
|
55
84
|
/** Available D1 database bindings */
|
|
56
85
|
shards: Record<string, D1Database>;
|
|
57
|
-
/** Default shard allocation strategy */
|
|
58
|
-
strategy?: ShardingStrategy;
|
|
86
|
+
/** Default shard allocation strategy (can be single strategy or mixed strategy object) */
|
|
87
|
+
strategy?: ShardingStrategy | MixedShardingStrategy;
|
|
88
|
+
/** Target region for location-based sharding */
|
|
89
|
+
targetRegion?: D1Region;
|
|
90
|
+
/** Geographic locations of each shard (required for location strategy) */
|
|
91
|
+
shardLocations?: Record<string, ShardLocation>;
|
|
92
|
+
/**
|
|
93
|
+
* Disable automatic migration detection and background migration (useful for testing)
|
|
94
|
+
* @since 1.0.2
|
|
95
|
+
*/
|
|
96
|
+
disableAutoMigration?: boolean;
|
|
59
97
|
}
|
|
60
98
|
/**
|
|
61
99
|
* Shard statistics for monitoring and load balancing
|
|
@@ -99,9 +137,15 @@ export interface ShardCoordinatorState {
|
|
|
99
137
|
* `round-robin` - distributes keys evenly across shards
|
|
100
138
|
* `random` - selects a random shard for each key
|
|
101
139
|
* `hash` - uses a hash function to determine shard based on primary key (default)
|
|
140
|
+
* `location` - selects shards based on geographic proximity to reduce latency
|
|
141
|
+
* Can also be a mixed strategy object with separate read/write strategies
|
|
102
142
|
*/
|
|
103
|
-
strategy: ShardingStrategy;
|
|
143
|
+
strategy: ShardingStrategy | MixedShardingStrategy;
|
|
104
144
|
/** Round-robin counter for allocation */
|
|
105
145
|
roundRobinIndex: number;
|
|
146
|
+
/** Target region for location-based allocation */
|
|
147
|
+
targetRegion?: D1Region;
|
|
148
|
+
/** Geographic locations of each shard */
|
|
149
|
+
shardLocations?: Record<string, ShardLocation>;
|
|
106
150
|
}
|
|
107
151
|
//# sourceMappingURL=types.d.ts.map
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEjG
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEjG;;GAEG;AACH,MAAM,MAAM,QAAQ,GACjB,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,IAAI,GACJ,IAAI,GACJ,IAAI,CAAC;AAER;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,gDAAgD;IAChD,MAAM,EAAE,QAAQ,CAAC;IACjB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9E;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC,4CAA4C;IAC5C,IAAI,EAAE,gBAAgB,CAAC;IACvB,6DAA6D;IAC7D,KAAK,EAAE,gBAAgB,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,GAAG;IACnB,wEAAwE;IACxE,EAAE,EAAE,WAAW,CAAC;IAChB,oDAAoD;IACpD,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,4DAA4D;IAC5D,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,wCAAwC;IACxC,EAAE,EAAE,WAAW,CAAC;IAChB,uCAAuC;IACvC,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,gBAAgB,GAAG,qBAAqB,CAAC;IACpD,gDAAgD;IAChD,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC/C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,2CAA2C;IAC3C,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CACnE;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,gCAAgC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,EAAE,gBAAgB,GAAG,qBAAqB,CAAC;IACnD,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC/C"}
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"main": "dist/index.js",
|
|
5
5
|
"types": "dist/index.d.ts",
|
|
6
6
|
"type": "module",
|
|
7
|
-
"version": "1.0.
|
|
7
|
+
"version": "1.0.2",
|
|
8
8
|
"files": [
|
|
9
9
|
"dist/**/*",
|
|
10
10
|
"README.md",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"jsdoc-babel": "^0.5.0",
|
|
38
38
|
"lint-staged": "^16.1.2",
|
|
39
39
|
"prettier": "^3.6.2",
|
|
40
|
-
"prettier-plugin-organize-imports": "
|
|
40
|
+
"prettier-plugin-organize-imports": "4.1.0",
|
|
41
41
|
"typedoc": "^0.28.8",
|
|
42
42
|
"vitest": "^3.2.4"
|
|
43
43
|
},
|