@earth-app/collegedb 1.0.1

package/dist/router.d.ts

@@ -0,0 +1,509 @@
+/**
+ * @fileoverview Main routing and query distribution logic for CollegeDB
+ *
+ * This module provides the core functionality for routing database queries to the
+ * appropriate D1 shard based on primary key mappings. It handles shard selection,
+ * database routing, and provides a unified API for CRUD operations across multiple
+ * distributed D1 databases.
+ *
+ * Key responsibilities:
+ * - Initialize and manage the global CollegeDB configuration
+ * - Route queries to appropriate shards based on primary key mappings
+ * - Implement shard allocation strategies (round-robin, random, hash-based)
+ * - Provide unified CRUD operations across distributed shards
+ * - Coordinate with Durable Objects for centralized shard management
+ * - Handle shard rebalancing and data migration
+ *
+ * @example
+ * ```typescript
+ * import { initialize, insert, first, run } from 'collegedb';
+ *
+ * // Initialize the system
+ * initialize({
+ *   kv: env.KV,
+ *   coordinator: env.ShardCoordinator,
+ *   shards: {
+ *     'db-east': env.DB_EAST,
+ *     'db-west': env.DB_WEST
+ *   },
+ *   strategy: 'hash'
+ * });
+ *
+ * // Insert a record (automatically routed to appropriate shard)
+ * await run('user-123', 'INSERT INTO users (id, name) VALUES (?, ?)', ['user-123', 'John']);
+ *
+ * // Query the record (routed to same shard)
+ * const result = await first('user-123', 'SELECT * FROM users WHERE id = ?', ['user-123']);
+ * ```
+ *
+ * @author CollegeDB Team
+ * @since 1.0.0
+ */
+import type { D1Database, D1PreparedStatement, D1Result } from '@cloudflare/workers-types';
+import type { CollegeDBConfig, ShardStats } from './types.js';
+/**
+ * Sets up the global configuration for the CollegeDB system. This must be called
+ * before any other operations can be performed. The configuration includes KV
+ * storage, available D1 shards, optional coordinator, and allocation strategy.
+ *
+ * This will also automatically detect and migrate existing databases without requiring
+ * additional setup. If shards contain existing data with primary keys, CollegeDB
+ * will automatically create the necessary mappings for seamless operation.
+ *
+ * @param config - Configuration object containing all necessary bindings and settings
+ * @throws {Error} If configuration is invalid or required bindings are missing
+ * @example
+ * ```typescript
+ * // Basic setup with multiple shards - auto-migration happens automatically
+ * initialize({
+ *   kv: env.KV,
+ *   shards: {
+ *     'db-primary': env.DB_PRIMARY,     // Existing DB with data
+ *     'db-secondary': env.DB_SECONDARY  // Another existing DB
+ *   },
+ *   strategy: 'round-robin'
+ * });
+ * // Existing data is now automatically accessible via CollegeDB!
+ *
+ * // Advanced setup with coordinator
+ * initialize({
+ *   kv: env.KV,
+ *   coordinator: env.ShardCoordinator,
+ *   shards: {
+ *     'db-east': env.DB_EAST,
+ *     'db-west': env.DB_WEST,
+ *     'db-central': env.DB_CENTRAL
+ *   },
+ *   strategy: 'hash'
+ * });
+ * ```
+ */
+export declare function initialize(config: CollegeDBConfig): void;
+/**
+ * Sets up the global configuration for the CollegeDB system asynchronously.
+ * This must be called before any other operations can be performed. The
+ * configuration includes KVstorage, available D1 shards, optional coordinator,
+ * and allocation strategy.
+ *
+ * This will also automatically detect and migrate existing databases without requiring
+ * additional setup. If shards contain existing data with primary keys, CollegeDB
+ * will automatically create the necessary mappings for seamless operation.
+ *
+ * Compared to `initialize`, this method waits for the background check to finish.
+ *
+ * @param config - Configuration object containing all necessary bindings and settings
+ * @throws {Error} If configuration is invalid or required bindings are missing
+ * @example
+ * ```typescript
+ * // Basic setup with multiple shards - auto-migration happens automatically
+ * initializeAsync({
+ *   kv: env.KV,
+ *   shards: {
+ *     'db-primary': env.DB_PRIMARY,     // Existing DB with data
+ *     'db-secondary': env.DB_SECONDARY  // Another existing DB
+ *   },
+ *   strategy: 'round-robin'
+ * });
+ * // Existing data is now automatically accessible via CollegeDB!
+ *
+ * // Advanced setup with coordinator
+ * initializeAsync({
+ *   kv: env.KV,
+ *   coordinator: env.ShardCoordinator,
+ *   shards: {
+ *     'db-east': env.DB_EAST,
+ *     'db-west': env.DB_WEST,
+ *     'db-central': env.DB_CENTRAL
+ *   },
+ *   strategy: 'hash'
+ * });
+ * ```
+ */
+export declare function initializeAsync(config: CollegeDBConfig): Promise<void>;
+/**
+ * Initializes the configuration and then performs a callback once the configuration
+ * has finished initializing.
+ *
+ * @param config - CollegeDB Configuration
+ * @param callback - The callback to perform after the initialization
+ * @returns The result of the callback
+ * @example
+ * ```
+ * import { collegedb, first } from 'collegedb'
+ *
+ * const result = collegedb({
+ *   kv: env.KV,
+ *   shards: {
+ *     'db-primary': env.DB_PRIMARY,     // Existing DB with data
+ *     'db-secondary': env.DB_SECONDARY  // Another existing DB
+ *   },
+ *   strategy: 'hash'
+ * }, async () => {
+ *     return await first('user-123', 'SELECT * FROM users WHERE id = ?', ['user-123']);
+ * });
+ * ```
+ */
+export declare function collegedb<T>(config: CollegeDBConfig, callback: () => T): Promise<T>;
+/**
+ * Creates the database schema in the specified D1 database
+ *
+ * @param d1 - The D1 database instance to create schema in
+ * @param schema - The SQL schema definition to execute
+ * @returns Promise that resolves when schema creation is complete
+ * @throws {Error} If schema creation fails
+ * @example
+ * ```typescript
+ * const userSchema = `
+ *   CREATE TABLE users (
+ *     id TEXT PRIMARY KEY,
+ *     name TEXT NOT NULL,
+ *     email TEXT UNIQUE
+ *   );
+ * `;
+ * await createSchema(env.DB_NEW_SHARD, userSchema);
+ * ```
+ */
+export declare function createSchema(d1: D1Database, schema: string): Promise<void>;
+/**
+ * Prepares a SQL statement for execution.
+ *
+ * @param key - The primary key to route the query
+ * @param sql - The SQL statement to prepare
+ * @returns Promise that resolves to a prepared statement
+ * @throws {Error} If preparation fails
+ */
+export declare function prepare(key: string, sql: string): Promise<D1PreparedStatement>;
+/**
+ * Executes a statement on the appropriate shard based on the primary key.
+ * The primary key is used to determine which shard should store the record,
+ * ensuring consistent routing for future queries.
+ *
+ * @template T - Type of the result records
+ * @param key - Primary key to route the query (should match the record's primary key)
+ * @param sql - SQL statement with parameter placeholders
+ * @param bindings - Parameter values to bind to the SQL statement
+ * @returns Promise that resolves when the statement is complete
+ * @throws {Error} If statement fails or routing fails
+ * @example
+ * ```typescript
+ * // Insert a new user
+ * await run('user-123',
+ *   'INSERT INTO users (id, name, email) VALUES (?, ?, ?)',
+ *   ['user-123', 'John Doe', 'john@example.com']
+ * );
+ *
+ * // Insert a post linked to a user
+ * await run('post-456',
+ *   'INSERT INTO posts (id, user_id, title, content) VALUES (?, ?, ?, ?)',
+ *   ['post-456', 'user-123', 'Hello World', 'My first post!']
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Update user information
+ * await run('user-123',
+ *   'UPDATE users SET name = ?, email = ? WHERE id = ?',
+ *   ['John Smith', 'johnsmith@example.com', 'user-123']
+ * );
+ *
+ * // Update post content
+ * await run('post-456',
+ *   'UPDATE posts SET title = ?, content = ?, updated_at = strftime("%s", "now") WHERE id = ?',
+ *   ['Updated Title', 'Updated content here', 'post-456']
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delete a specific user
+ * await run('user-123',
+ *   'DELETE FROM users WHERE id = ?',
+ *   ['user-123']
+ * );
+ *
+ * // Delete user's posts (cascade delete)
+ * await run('user-123',
+ *   'DELETE FROM posts WHERE user_id = ?',
+ *   ['user-123']
+ * );
+ *
+ * // Delete with conditions
+ * await run('user-123',
+ *   'DELETE FROM posts WHERE user_id = ? AND created_at < ?',
+ *   ['user-123', Date.now() - 86400000] // Posts older than 1 day
+ * );
+ * ```
+ */
+export declare function run<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+/**
+ * Retrieves all records matching the query for a given primary key.
+ *
+ * This function is useful for fetching multiple records based on a primary key.
+ * It automatically routes the query to the correct shard based on the provided
+ * primary key, ensuring consistent data access.
+ * @param key - Primary key to route the query
+ * @param sql - The SQL statement to execute
+ * @param bindings - Parameter values to bind to the SQL statement
+ * @returns Promise that resolves to the result of the update operation
+ * @throws {Error} If update fails or routing fails
+ *
+ * @example
+ * ```typescript
+ * type Post = {
+ *  id: string;
+ *  user_id: string;
+ *  title: string;
+ *  content: string;
+ * };
+ *
+ *
+ * // Get user's posts
+ * const postsResult = await all<Post>('user-123',
+ *   'SELECT * FROM posts WHERE user_id = ? ORDER BY created_at DESC',
+ *   ['user-123']
+ * );
+ *
+ * console.log(`User has ${postsResult.meta.count} posts`);
+ * ```
+ */
+export declare function all<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+/**
+ * Retrieves the first record matching the query for a given primary key.
+ *
+ * This function is useful for fetching a single record based on a primary key.
+ * It automatically routes the query to the correct shard based on the provided
+ * primary key, ensuring consistent data access.
+ *
+ * @template T - Type of the result record
+ * @param key - Primary key to route the query
+ * @param sql - SQL statement with parameter placeholders
+ * @param bindings - Parameter values to bind to the SQL statement
+ * @returns Promise that resolves to the first matching record, or null if not found
+ * @throws {Error} If query fails or routing fails
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * };
+ * // Get a specific user
+ * const userResult = await first<User>('user-123',
+ *   'SELECT * FROM users WHERE id = ?',
+ *   ['user-123']
+ * );
+ *
+ * if (userResult) {
+ *   console.log(`Found user: ${userResult.name}`);
+ * }
+ */
+export declare function first<T = Record<string, unknown>>(key: string, sql: string, bindings?: any[]): Promise<T | null>;
+/**
+ * Reassigns a primary key to a different shard
+ *
+ * Moves a primary key and its associated data from one shard to another. This
+ * operation is useful for load balancing, shard maintenance, or geographic
+ * redistribution of data.
+ *
+ * The reassignment process:
+ * 1. Validates the target shard exists in configuration
+ * 2. Checks that a mapping exists for the primary key
+ * 3. If target shard differs from current, migrates the data
+ * 4. Updates the KV mapping to point to the new shard
+ *
+ * **Note**: This operation involves data migration and should be used
+ * carefully in production environments. Consider the impact on ongoing queries.
+ *
+ * @param primaryKey - Primary key to reassign to a different shard
+ * @param newBinding - New shard binding name where the data should be moved
+ * @param tableName - Name of the table containing the record to migrate
+ * @returns Promise that resolves when reassignment and migration are complete
+ * @throws {Error} If target shard not found, mapping doesn't exist, or migration fails
+ * @example
+ * ```typescript
+ * // Move a user from east to west coast for better latency
+ * try {
+ *   await reassignShard('user-california-123', 'db-west', 'users');
+ *   console.log('User successfully moved to west coast shard');
+ * } catch (error) {
+ *   console.error('Reassignment failed:', error.message);
+ * }
+ *
+ * // Load balancing: move high-activity user to dedicated shard
+ * await reassignShard('user-enterprise-456', 'db-dedicated', 'users');
+ * ```
+ */
+export declare function reassignShard(primaryKey: string, newBinding: string, tableName: string): Promise<void>;
+/**
+ * Lists all known shards
+ *
+ * Returns an array of all shard binding names known to the system. First
+ * attempts to get the list from the Durable Object coordinator for the most
+ * up-to-date information, then falls back to the configured shards if the
+ * coordinator is unavailable.
+ *
+ * @returns Promise resolving to array of shard binding names
+ * @example
+ * ```typescript
+ * const shards = await listKnownShards();
+ * console.log('Available shards:', shards);
+ * // Output: ['db-east', 'db-west', 'db-central']
+ *
+ * // Check if a specific shard is available
+ * if (shards.includes('db-asia')) {
+ *   console.log('Asia region shard is available');
+ * }
+ * ```
+ */
+export declare function listKnownShards(): Promise<string[]>;
+/**
+ * Gets statistics for all shards
+ *
+ * Returns usage statistics for all known shards, including key counts and
+ * last updated timestamps. First attempts to get real-time statistics from
+ * the Durable Object coordinator, then falls back to KV-based counting.
+ *
+ * This information is useful for:
+ * - Load balancing decisions
+ * - Monitoring shard utilization
+ * - Capacity planning
+ * - Performance analysis
+ *
+ * @returns Promise resolving to array of shard statistics
+ * @example
+ * ```typescript
+ * const stats = await getShardStats();
+ * stats.forEach(shard => {
+ *   console.log(`${shard.binding}: ${shard.count} keys`);
+ *   if (shard.lastUpdated) {
+ *     console.log(`  Last updated: ${new Date(shard.lastUpdated)}`);
+ *   }
+ * });
+ *
+ * // Find most loaded shard
+ * const mostLoaded = stats.reduce((prev, current) =>
+ *   (prev.count > current.count) ? prev : current
+ * );
+ * console.log(`Most loaded shard: ${mostLoaded.binding} (${mostLoaded.count} keys)`);
+ * ```
+ */
+export declare function getShardStats(): Promise<ShardStats[]>;
+/**
+ * Bypasses the normal routing logic to execute a query directly on a specified
+ * shard. This is useful for administrative operations, cross-shard queries,
+ * or when you need to query data that doesn't follow the primary key routing pattern.
+ *
+ * **Use with caution**: This function bypasses routing safeguards and should
+ * be used only when you specifically need to target a particular shard.
+ *
+ * @param shardBinding - The shard binding name to execute the query on
+ * @param sql - SQL statement to execute
+ * @param bindings - Parameter values to bind to the SQL statement
+ * @returns Promise resolving to the result of the query execution
+ * @throws {Error} If shard not found or query fails
+ * @example
+ * ```typescript
+ * // Administrative query: insert a new user directly into a specific shard
+ * const result = await runShard('db-east',
+ *   'INSERT INTO users (id, name, email) VALUES (?, ?, ?)',
+ *   ['user-789', 'Alice', 'alice@example.com']
+ * );
+ * console.log(`Inserted user with ID: ${result.lastInsertId}`);
+ * ```
+ */
+export declare function runShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+/**
+ * Bypasses the normal routing logic to execute a query directly on a specified
+ * shard. This is useful for administrative operations, cross-shard queries,
+ * or when you need to query data that doesn't follow the primary key routing pattern.
+ *
+ * **Use with caution**: This function bypasses routing safeguards and should
+ * be used only when you specifically need to target a particular shard.
+ *
+ * @param shardBinding - The shard binding name to execute the query on
+ * @param sql - SQL statement to execute
+ * @param bindings - Parameter values to bind to the SQL statement
+ * @returns Promise resolving to structured query results
+ * @throws {Error} If shard not found or query fails
+ * @example
+ * ```typescript
+ * // Administrative query: count all users across a specific shard
+ * const eastCoastStats = await allShard('db-east',
+ *   'SELECT COUNT(*) as user_count FROM users'
+ * );
+ * console.log(`East coast users: ${eastCoastStats.results[0].user_count}`);
+ *
+ * // Cross-shard analytics: get recent posts from a specific region
+ * const recentPosts = await allShard('db-west',
+ *   'SELECT id, title, created_at FROM posts WHERE created_at > ? ORDER BY created_at DESC LIMIT ?',
+ *   [Date.now() - 86400000, 10] // Last 24 hours, limit 10
+ * );
+ *
+ * // Schema inspection on specific shard
+ * const tables = await allShard('db-central',
+ *   "SELECT name FROM sqlite_master WHERE type='table'"
+ * );
+ * ```
+ */
+export declare function allShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<D1Result<T>>;
+/**
+ * Bypasses the normal routing logic to execute a query directly on a specified
+ * shard. This is useful for administrative operations, cross-shard queries,
+ * or when you need to query data that doesn't follow the primary key routing pattern.
+ *
+ * **Use with caution**: This function bypasses routing safeguards and should
+ * be used only when you specifically need to target a particular shard.
+ *
+ * @param shardBinding - The shard binding name to execute the query on
+ * @param sql - SQL statement to execute
+ * @param bindings - Parameter values to bind to the SQL statement
+ * @returns Promise resolving to the first matching record, or null if not found
+ * @throws {Error} If shard not found or query fails
+ * @example
+ * ```typescript
+ * // Administrative query: get a specific user from a shard
+ * const user = await firstShard('db-east',
+ *  'SELECT * FROM users WHERE id = ?',
+ *   ['user-123']);
+ * if (user) {
+ *   console.log(`Found user: ${user.name}`);
+ * } else {
+ *   console.log('User not found in east shard');
+ * }
+ * ```
+ */
+export declare function firstShard<T = Record<string, unknown>>(shardBinding: string, sql: string, bindings?: any[]): Promise<T | null>;
+/**
+ * Flushes all shard mappings (development only)
+ *
+ * Completely clears all primary key to shard mappings from both KV storage
+ * and the Durable Object coordinator. This operation resets the entire
+ * routing system to a clean state.
+ *
+ * **DANGER**: This operation is destructive and irreversible. After flushing,
+ * all existing primary keys will be treated as new and may be assigned to
+ * different shards than before, causing data routing issues.
+ *
+ * **Use only for**:
+ * - Development and testing environments
+ * - Complete system resets
+ * - Emergency recovery scenarios
+ *
+ * @returns Promise that resolves when all mappings are cleared
+ * @example
+ * ```typescript
+ * // Only use in development!
+ * if (process.env.NODE_ENV === 'development') {
+ *   await flush();
+ *   console.log('All shard mappings cleared for testing');
+ *
+ *   // Now all keys will be reassigned on next access
+ *   await run('user-123', 'INSERT INTO users (id, name) VALUES (?, ?)',
+ *     ['user-123', 'Test User']);
+ * }
+ * ```
+ */
+export declare function flush(): Promise<void>;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview TypeScript type definitions for CollegeDB
+ *
+ * This module contains all the TypeScript interfaces and types used throughout
+ * the CollegeDB library. These types provide compile-time safety and enable
+ * better developer experience with IDE autocompletion and error checking.
+ *
+ * The types are organized into several categories:
+ * - Environment and configuration types
+ * - Query result and metadata types
+ * - Shard management and statistics types
+ * - Strategy and coordination types
+ *
+ * @example
+ * ```typescript
+ * import type { CollegeDBConfig, QueryResult, ShardStats } from './types.js';
+ *
+ * const config: CollegeDBConfig = {
+ *   kv: env.KV,
+ *   shards: { 'db-east': env.DB_EAST },
+ *   strategy: 'hash'
+ * };
+ * ```
+ *
+ * @author Gregory Mitchell
+ * @since 1.0.0
+ */
+import type { D1Database, DurableObjectNamespace, KVNamespace } from '@cloudflare/workers-types';
+/**
+ * Sharding strategy options for CollegeDB
+ * - `round-robin`: Distributes keys evenly across available shards.
+ * - `random`: Selects a random shard for each key.
+ * - `hash`: Uses a hash function to determine the shard based on the primary key.
+ */
+export type ShardingStrategy = 'round-robin' | 'random' | 'hash';
+/**
+ * Environment bindings for the Cloudflare Worker
+ */
+export interface Env {
+    /** Cloudflare KV namespace for storing primary key to shard mappings */
+    KV: KVNamespace;
+    /** Durable Object binding for shard coordination */
+    ShardCoordinator: DurableObjectNamespace;
+    /** D1 database bindings - dynamic based on wrangler.toml */
+    [key: string]: any;
+}
+/**
+ * Configuration for the collegedb sharded database
+ */
+export interface CollegeDBConfig {
+    /** KV namespace for storing mappings */
+    kv: KVNamespace;
+    /** Shard coordinator Durable Object */
+    coordinator?: DurableObjectNamespace;
+    /** Available D1 database bindings */
+    shards: Record<string, D1Database>;
+    /** Default shard allocation strategy */
+    strategy?: ShardingStrategy;
+}
+/**
+ * Shard statistics for monitoring and load balancing
+ */
+export interface ShardStats {
+    /** D1 binding name */
+    binding: string;
+    /** Number of primary keys assigned to this shard */
+    count: number;
+    /** Last updated timestamp */
+    lastUpdated?: number;
+}
+/**
+ * Shard allocation strategy interface
+ */
+export interface ShardStrategy {
+    /** Select a shard for a new primary key */
+    selectShard(primaryKey: string, availableShards: string[]): string;
+}
+/**
+ * Primary key to shard mapping stored in KV
+ */
+export interface ShardMapping {
+    /** D1 binding name */
+    shard: string;
+    /** Timestamp when mapping was created */
+    createdAt: number;
+    /** Timestamp when mapping was last updated */
+    updatedAt: number;
+}
+/**
+ * Durable Object state for shard coordination
+ */
+export interface ShardCoordinatorState {
+    /** List of known D1 bindings */
+    knownShards: string[];
+    /** Statistics for each shard */
+    shardStats: Record<string, ShardStats>;
+    /**
+     * Current allocation strategy
+     * `round-robin` - distributes keys evenly across shards
+     * `random` - selects a random shard for each key
+     * `hash` - uses a hash function to determine shard based on primary key (default)
+     */
+    strategy: ShardingStrategy;
+    /** Round-robin counter for allocation */
+    roundRobinIndex: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE;;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,wCAAwC;IACxC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC5B;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;;;;;OAKG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;CACxB"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@earth-app/collegedb",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "version": "1.0.1",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir=dist --target=node --format=esm --minify --sourcemap=linked && bunx tsc --project tsconfig.build.json",
+    "docs:build": "bunx typedoc src --out ./typedoc",
+    "prettier": "bunx prettier --write .",
+    "prettier:check": "bunx prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "husky install"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^4.20250726.0"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.28.0",
+    "@babel/core": "^7.28.0",
+    "@babel/preset-env": "^7.28.0",
+    "@babel/preset-typescript": "^7.27.1",
+    "@types/bun": "latest",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "jsdoc-babel": "^0.5.0",
+    "lint-staged": "^16.1.2",
+    "prettier": "^3.6.2",
+    "prettier-plugin-organize-imports": "^4.2.0",
+    "typedoc": "^0.28.8",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "lint-staged": {
+    "*.{js,ts,css,md}": "prettier --write"
+  }
+}