🗄️ JsonDB API

A document database API built for Val Town

\n \n

Quick Start

\n# Create a document\ncurl -X POST ${c.req.url}collections/users/documents \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"name\": \"John Doe\", \"email\": \"john@example.com\", \"age\": 30}'\n\n# Get all documents\ncurl ${c.req.url}collections/users/documents\n\n# Get document by ID\ncurl ${c.req.url}collections/users/documents/{id}\n\n# Update document\ncurl -X PUT ${c.req.url}collections/users/documents/{id} \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"age\": 31}'\n\n# Delete document\ncurl -X DELETE ${c.req.url}collections/users/documents/{id}\n

\n\n

API Endpoints

\n GET /health - Health check\n

\n GET /stats - Database statistics\n

\n GET /collections - List collections\n

\n POST /collections - Create collection\n

\n GET /collections/{name}/documents - Find documents\n

\n POST /collections/{name}/documents - Create document\n

\n GET /collections/{name}/documents/{id} - Get document\n

\n PUT /collections/{name}/documents/{id} - Update document\n

\n DELETE /collections/{name}/documents/{id} - Delete document\n

\n\n

Query Parameters

limit - Number of documents to return
offset - Number of documents to skip
sort - JSON array: [{\"field\": \"name\", \"direction\": \"asc\"}]
where - JSON object: {\"field\": \"value\"}

\n\n

Example Usage

\n# Find users over 25, sorted by name\ncurl \"${c.req.url}collections/users/documents?where=%7B%22age%22:%7B%22$gte%22:25%7D%7D&sort=%5B%7B%22field%22:%22name%22,%22direction%22:%22asc%22%7D%5D\"\n\n# Paginate results\ncurl \"${c.req.url}collections/users/documents?limit=10&offset=20\"\n

\n\n`;\n \n return c.html(html);\n});\n\n// Health check\napp.get('/health', (c) => {\n return c.json({ \n status: 'ok', \n timestamp: new Date().toISOString(),\n service: 'JsonDB API'\n });\n});\n\n// Database stats\napp.get('/stats', async (c) => {\n try {\n const stats = await jsonDb.getStats();\n return c.json(stats);\n } catch (error) {\n return c.json({ error: 'Failed to get stats' }, 500);\n }\n});\n\n// List collections\napp.get('/collections', async (c) => {\n try {\n const collections = await jsonDb.listCollections();\n return c.json({ collections });\n } catch (error) {\n return c.json({ error: 'Failed to list collections' }, 500);\n }\n});\n\n// Create collection\napp.post('/collections', async (c) => {\n try {\n const { name } = c.get('body') || {};\n if (!name) {\n return c.json({ error: 'Collection name required' }, 400);\n }\n\n const success = await jsonDb.createCollection(name);\n if (success) {\n return c.json({ message: `Collection '${name}' created` });\n } else {\n return c.json({ error: 'Failed to create collection' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to create collection' }, 500);\n }\n});\n\n// Get documents\napp.get('/collections/:name/documents', async (c) => {\n try {\n const collection = c.req.param('name');\n const limit = c.req.query('limit');\n const offset = c.req.query('offset');\n const sort = c.req.query('sort');\n const where = c.req.query('where');\n\n const options: any = {};\n if (limit) options.limit = parseInt(limit);\n if (offset) options.offset = parseInt(offset);\n if (sort) {\n try {\n options.sort = JSON.parse(sort);\n } catch (error) {\n return c.json({ error: 'Invalid sort parameter' }, 400);\n }\n }\n if (where) {\n try {\n options.where = JSON.parse(where);\n } catch (error) {\n return c.json({ error: 'Invalid where parameter' }, 400);\n }\n }\n\n const documents = await jsonDb.find(collection, options);\n return c.json({ documents });\n } catch (error) {\n return c.json({ error: 'Failed to find documents' }, 500);\n }\n});\n\n// Create document\napp.post('/collections/:name/documents', async (c) => {\n try {\n const collection = c.req.param('name');\n const document = c.get('body');\n \n if (!document) {\n return c.json({ error: 'Document data required' }, 400);\n }\n\n const result = await jsonDb.insert(collection, document);\n \n if (result.success) {\n return c.json({ \n message: 'Document created',\n id: result.id \n }, 201);\n } else {\n return c.json({ error: 'Failed to create document' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to create document' }, 500);\n }\n});\n\n// Get document by ID\napp.get('/collections/:name/documents/:id', async (c) => {\n try {\n const collection = c.req.param('name');\n const id = c.req.param('id');\n \n const document = await jsonDb.findById(collection, id);\n \n if (document) {\n return c.json({ document });\n } else {\n return c.json({ error: 'Document not found' }, 404);\n }\n } catch (error) {\n return c.json({ error: 'Failed to find document' }, 500);\n }\n});\n\n// Update document\napp.put('/collections/:name/documents/:id', async (c) => {\n try {\n const collection = c.req.param('name');\n const id = c.req.param('id');\n const update = c.get('body');\n \n if (!update) {\n return c.json({ error: 'Update data required' }, 400);\n }\n\n const result = await jsonDb.updateById(collection, id, update);\n \n if (result.success) {\n return c.json({ \n message: 'Document updated',\n modifiedCount: result.modifiedCount \n });\n } else {\n return c.json({ error: 'Failed to update document' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to update document' }, 500);\n }\n});\n\n// Delete document\napp.delete('/collections/:name/documents/:id', async (c) => {\n try {\n const collection = c.req.param('name');\n const id = c.req.param('id');\n \n const result = await jsonDb.deleteById(collection, id);\n \n if (result.success) {\n return c.json({ \n message: 'Document deleted',\n deletedCount: result.deletedCount \n });\n } else {\n return c.json({ error: 'Failed to delete document' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to delete document' }, 500);\n }\n});\n\n// This is the entry point for HTTP vals\nexport default app.fetch;\n\n",[],[150,179],{"_102":188,"_95":189,"_151":190,"_153":152,"_154":136,"_155":191,"_157":158,"_104":192,"_99":32,"_160":183,"_162":193,"_163":22,"_164":-5,"_165":194,"_98":195},"1d875ed0-9464-11f0-87ab-0224a6c84d84","val-town-http.ts","1d875f8e-9464-11f0-87ab-0224a6c84d84",10,["D",1758181815809],"/**\n * Val Town HTTP API example using JsonDB\n * This demonstrates how to create a REST API using the JSON database\n */\n\nimport { Hono } from \"https://esm.sh/hono@3.12.6\";\nimport { jsonDb } from \"../src/json-db.ts\";\n\nconst app = new Hono();\n\n// Unwrap Hono errors to see original error details\napp.onError((err, c) => {\n throw err;\n});\n\n// Middleware for JSON parsing\napp.use('*', async (c, next) => {\n if (c.req.method === 'POST' || c.req.method === 'PUT' || c.req.method === 'PATCH') {\n try {\n const body = await c.req.json();\n c.set('body', body);\n } catch (error) {\n return c.json({ error: 'Invalid JSON' }, 400);\n }\n }\n await next();\n});\n\n// Health check endpoint\napp.get('/health', (c) => {\n return c.json({ status: 'ok', timestamp: new Date().toISOString() });\n});\n\n// Database stats endpoint\napp.get('/stats', async (c) => {\n try {\n const stats = await jsonDb.getStats();\n return c.json(stats);\n } catch (error) {\n return c.json({ error: 'Failed to get database stats' }, 500);\n }\n});\n\n// Collection management endpoints\napp.get('/collections', async (c) => {\n try {\n const collections = await jsonDb.listCollections();\n return c.json({ collections });\n } catch (error) {\n return c.json({ error: 'Failed to list collections' }, 500);\n }\n});\n\napp.post('/collections', async (c) => {\n try {\n const { name } = c.get('body') || {};\n if (!name) {\n return c.json({ error: 'Collection name is required' }, 400);\n }\n\n const success = await jsonDb.createCollection(name);\n if (success) {\n return c.json({ message: `Collection '${name}' created successfully` });\n } else {\n return c.json({ error: 'Failed to create collection' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to create collection' }, 500);\n }\n});\n\napp.delete('/collections/:name', async (c) => {\n try {\n const name = c.req.param('name');\n const success = await jsonDb.dropCollection(name);\n \n if (success) {\n return c.json({ message: `Collection '${name}' deleted successfully` });\n } else {\n return c.json({ error: 'Collection not found or could not be deleted' }, 404);\n }\n } catch (error) {\n return c.json({ error: 'Failed to delete collection' }, 500);\n }\n});\n\napp.get('/collections/:name/stats', async (c) => {\n try {\n const name = c.req.param('name');\n const stats = await jsonDb.getCollectionStats(name);\n \n if (stats) {\n return c.json(stats);\n } else {\n return c.json({ error: 'Collection not found' }, 404);\n }\n } catch (error) {\n return c.json({ error: 'Failed to get collection stats' }, 500);\n }\n});\n\n// Document CRUD endpoints\napp.post('/collections/:name/documents', async (c) => {\n try {\n const collection = c.req.param('name');\n const document = c.get('body');\n \n if (!document) {\n return c.json({ error: 'Document data is required' }, 400);\n }\n\n const result = await jsonDb.insert(collection, document);\n \n if (result.success) {\n return c.json({ \n message: 'Document created successfully',\n id: result.id \n }, 201);\n } else {\n return c.json({ error: 'Failed to create document' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to create document' }, 500);\n }\n});\n\napp.post('/collections/:name/documents/batch', async (c) => {\n try {\n const collection = c.req.param('name');\n const { documents } = c.get('body') || {};\n \n if (!Array.isArray(documents)) {\n return c.json({ error: 'Documents array is required' }, 400);\n }\n\n const results = await jsonDb.insertMany(collection, documents);\n const successCount = results.filter(r => r.success).length;\n \n return c.json({ \n message: `Created ${successCount} out of ${documents.length} documents`,\n results \n }, 201);\n } catch (error) {\n return c.json({ error: 'Failed to create documents' }, 500);\n }\n});\n\napp.get('/collections/:name/documents', async (c) => {\n try {\n const collection = c.req.param('name');\n const limit = c.req.query('limit');\n const offset = c.req.query('offset');\n const sort = c.req.query('sort');\n const where = c.req.query('where');\n\n const options: any = {};\n \n if (limit) options.limit = parseInt(limit);\n if (offset) options.offset = parseInt(offset);\n if (sort) {\n try {\n options.sort = JSON.parse(sort);\n } catch (error) {\n return c.json({ error: 'Invalid sort parameter' }, 400);\n }\n }\n if (where) {\n try {\n options.where = JSON.parse(where);\n } catch (error) {\n return c.json({ error: 'Invalid where parameter' }, 400);\n }\n }\n\n const documents = await jsonDb.find(collection, options);\n return c.json({ documents });\n } catch (error) {\n return c.json({ error: 'Failed to find documents' }, 500);\n }\n});\n\napp.get('/collections/:name/documents/:id', async (c) => {\n try {\n const collection = c.req.param('name');\n const id = c.req.param('id');\n \n const document = await jsonDb.findById(collection, id);\n \n if (document) {\n return c.json({ document });\n } else {\n return c.json({ error: 'Document not found' }, 404);\n }\n } catch (error) {\n return c.json({ error: 'Failed to find document' }, 500);\n }\n});\n\napp.put('/collections/:name/documents/:id', async (c) => {\n try {\n const collection = c.req.param('name');\n const id = c.req.param('id');\n const update = c.get('body');\n \n if (!update) {\n return c.json({ error: 'Update data is required' }, 400);\n }\n\n const result = await jsonDb.updateById(collection, id, update);\n \n if (result.success) {\n return c.json({ \n message: 'Document updated successfully',\n modifiedCount: result.modifiedCount \n });\n } else {\n return c.json({ error: 'Failed to update document' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to update document' }, 500);\n }\n});\n\napp.patch('/collections/:name/documents', async (c) => {\n try {\n const collection = c.req.param('name');\n const { where, update } = c.get('body') || {};\n \n if (!where || !update) {\n return c.json({ error: 'where and update are required' }, 400);\n }\n\n const result = await jsonDb.update(collection, where, update);\n \n return c.json({ \n message: 'Documents updated successfully',\n modifiedCount: result.modifiedCount \n });\n } catch (error) {\n return c.json({ error: 'Failed to update documents' }, 500);\n }\n});\n\napp.delete('/collections/:name/documents/:id', async (c) => {\n try {\n const collection = c.req.param('name');\n const id = c.req.param('id');\n \n const result = await jsonDb.deleteById(collection, id);\n \n if (result.success) {\n return c.json({ \n message: 'Document deleted successfully',\n deletedCount: result.deletedCount \n });\n } else {\n return c.json({ error: 'Failed to delete document' }, 500);\n }\n } catch (error) {\n return c.json({ error: 'Failed to delete document' }, 500);\n }\n});\n\napp.delete('/collections/:name/documents', async (c) => {\n try {\n const collection = c.req.param('name');\n const { where } = c.get('body') || {};\n \n if (!where) {\n return c.json({ error: 'where condition is required' }, 400);\n }\n\n const result = await jsonDb.delete(collection, where);\n \n return c.json({ \n message: 'Documents deleted successfully',\n deletedCount: result.deletedCount \n });\n } catch (error) {\n return c.json({ error: 'Failed to delete documents' }, 500);\n }\n});\n\napp.get('/collections/:name/count', async (c) => {\n try {\n const collection = c.req.param('name');\n const where = c.req.query('where');\n \n let whereCondition;\n if (where) {\n try {\n whereCondition = JSON.parse(where);\n } catch (error) {\n return c.json({ error: 'Invalid where parameter' }, 400);\n }\n }\n\n const count = await jsonDb.count(collection, whereCondition);\n return c.json({ count });\n } catch (error) {\n return c.json({ error: 'Failed to count documents' }, 500);\n }\n});\n\n// Root endpoint with API documentation\napp.get('/', (c) => {\n const apiDocs = {\n name: \"JsonDB REST API\",\n version: \"1.0.0\",\n description: \"A REST API for the JsonDB document database\",\n endpoints: {\n \"GET /health\": \"Health check\",\n \"GET /stats\": \"Get database statistics\",\n \"GET /collections\": \"List all collections\",\n \"POST /collections\": \"Create a new collection\",\n \"DELETE /collections/:name\": \"Delete a collection\",\n \"GET /collections/:name/stats\": \"Get collection statistics\",\n \"POST /collections/:name/documents\": \"Create a document\",\n \"POST /collections/:name/documents/batch\": \"Create multiple documents\",\n \"GET /collections/:name/documents\": \"Find documents with optional query parameters\",\n \"GET /collections/:name/documents/:id\": \"Get a document by ID\",\n \"PUT /collections/:name/documents/:id\": \"Update a document by ID\",\n \"PATCH /collections/:name/documents\": \"Update multiple documents\",\n \"DELETE /collections/:name/documents/:id\": \"Delete a document by ID\",\n \"DELETE /collections/:name/documents\": \"Delete multiple documents\",\n \"GET /collections/:name/count\": \"Count documents with optional where condition\"\n },\n queryParameters: {\n \"limit\": \"Number of documents to return\",\n \"offset\": \"Number of documents to skip\",\n \"sort\": \"JSON array of sort objects: [{\\\"field\\\": \\\"name\\\", \\\"direction\\\": \\\"asc\\\"}]\",\n \"where\": \"JSON object for filtering: {\\\"field\\\": \\\"value\\\"}\"\n }\n };\n \n return c.json(apiDocs);\n});\n\n// This is the entry point for HTTP vals\nexport default app.fetch;\n\n",[],[150,189],[150],{"_102":198,"_95":199,"_151":200,"_153":-5,"_154":136,"_155":201,"_157":158,"_104":202,"_99":32,"_160":161,"_162":-5,"_163":22,"_164":-5,"_165":203,"_98":231},"1d17cd2c-9464-11f0-99cc-0224a6c84d84","src","1d17cf48-9464-11f0-99cc-0224a6c84d84",2,["D",1758181815414],[204,213,222],{"_102":205,"_95":206,"_151":207,"_153":200,"_154":136,"_155":208,"_157":158,"_104":209,"_99":32,"_160":173,"_162":210,"_163":22,"_164":-5,"_165":211,"_98":212},"1d7131d2-9464-11f0-9a85-0224a6c84d84","index.ts","1d71327c-9464-11f0-9a85-0224a6c84d84",8,["D",1758181815985],"/**\n * JsonDB - Main entry point\n * A document database abstraction over SQLite for Val Town\n */\n\n// Export the main JsonDB class and default instance\nexport { JsonDB, jsonDb, type Document, type QueryOptions, type CollectionStats, type InsertResult, type UpdateResult, type DeleteResult } from \"./json-db.ts\";\n\n// Export migration utilities\nexport { MigrationManager, migrationManager, type Migration, type MigrationResult } from \"./migrations.ts\";\n\n// Re-export for convenience\nexport { jsonDb as default } from \"./json-db.ts\";\n\n",[],[199,206],{"_102":214,"_95":215,"_151":216,"_153":200,"_154":136,"_155":217,"_157":158,"_104":218,"_99":32,"_160":173,"_162":219,"_163":22,"_164":-5,"_165":220,"_98":221},"1e17af12-9464-11f0-a205-0224a6c84d84","json-db.ts","1e17afda-9464-11f0-a205-0224a6c84d84",12,["D",1758181815813],"import { sqlite } from \"https://esm.town/v/std/sqlite\";\n\n// Type definitions for the JSON database\nexport interface Document {\n id?: string;\n [key: string]: any;\n}\n\nexport interface QueryOptions {\n limit?: number;\n offset?: number;\n sort?: { field: string; direction: 'asc' | 'desc' }[];\n where?: Record;\n}\n\nexport interface CollectionStats {\n name: string;\n count: number;\n createdAt: string;\n lastModified: string;\n}\n\nexport interface InsertResult {\n id: string;\n success: boolean;\n}\n\nexport interface UpdateResult {\n modifiedCount: number;\n success: boolean;\n}\n\nexport interface DeleteResult {\n deletedCount: number;\n success: boolean;\n}\n\n/**\n * JSON Database - A document database abstraction over SQLite\n * Provides MongoDB-like interface for Val Town's SQLite\n */\nexport class JsonDB {\n private initialized = false;\n private collections = new Set();\n\n constructor() {\n // Auto-initialize on construction\n this.initialize();\n }\n\n /**\n * Initialize the database and create necessary tables\n */\n private async initialize(): Promise {\n if (this.initialized) return;\n\n try {\n // Create the main collections metadata table\n await sqlite.execute(`\n CREATE TABLE IF NOT EXISTS _collections_metadata (\n name TEXT PRIMARY KEY,\n created_at TEXT NOT NULL,\n last_modified TEXT NOT NULL,\n schema_version INTEGER DEFAULT 1\n )\n `);\n\n // Create the documents table with JSON storage\n await sqlite.execute(`\n CREATE TABLE IF NOT EXISTS _documents (\n id TEXT PRIMARY KEY,\n collection TEXT NOT NULL,\n data TEXT NOT NULL,\n created_at TEXT NOT NULL,\n updated_at TEXT NOT NULL,\n FOREIGN KEY (collection) REFERENCES _collections_metadata(name)\n )\n `);\n\n // Create indexes for better performance\n await sqlite.execute(`\n CREATE INDEX IF NOT EXISTS idx_documents_collection ON _documents(collection)\n `);\n \n await sqlite.execute(`\n CREATE INDEX IF NOT EXISTS idx_documents_created_at ON _documents(created_at)\n `);\n\n // Load existing collections\n const result = await sqlite.execute(`SELECT name FROM _collections_metadata`);\n for (const row of result.rows) {\n this.collections.add(row[0] as string);\n }\n\n this.initialized = true;\n } catch (error) {\n console.error('Failed to initialize JsonDB:', error);\n throw error;\n }\n }\n\n /**\n * Ensure database is initialized before operations\n */\n private async ensureInitialized(): Promise {\n if (!this.initialized) {\n await this.initialize();\n }\n }\n\n /**\n * Generate a unique ID for documents\n */\n private generateId(): string {\n return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n }\n\n /**\n * Get current timestamp\n */\n private getTimestamp(): string {\n return new Date().toISOString();\n }\n\n /**\n * Create a new collection\n */\n async createCollection(name: string): Promise {\n await this.ensureInitialized();\n\n if (this.collections.has(name)) {\n return true; // Collection already exists\n }\n\n try {\n const timestamp = this.getTimestamp();\n await sqlite.execute(\n `INSERT INTO _collections_metadata (name, created_at, last_modified) VALUES (?, ?, ?)`,\n [name, timestamp, timestamp]\n );\n\n this.collections.add(name);\n return true;\n } catch (error) {\n console.error(`Failed to create collection ${name}:`, error);\n return false;\n }\n }\n\n /**\n * Drop a collection and all its documents\n */\n async dropCollection(name: string): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(name)) {\n return false; // Collection doesn't exist\n }\n\n try {\n // Delete all documents in the collection\n await sqlite.execute(`DELETE FROM _documents WHERE collection = ?`, [name]);\n \n // Delete collection metadata\n await sqlite.execute(`DELETE FROM _collections_metadata WHERE name = ?`, [name]);\n\n this.collections.delete(name);\n return true;\n } catch (error) {\n console.error(`Failed to drop collection ${name}:`, error);\n return false;\n }\n }\n\n /**\n * List all collections\n */\n async listCollections(): Promise {\n await this.ensureInitialized();\n return Array.from(this.collections);\n }\n\n /**\n * Get collection statistics\n */\n async getCollectionStats(name: string): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(name)) {\n return null;\n }\n\n try {\n // Get collection metadata\n const metaResult = await sqlite.execute(\n `SELECT created_at, last_modified FROM _collections_metadata WHERE name = ?`,\n [name]\n );\n\n if (metaResult.rows.length === 0) {\n return null;\n }\n\n // Get document count\n const countResult = await sqlite.execute(\n `SELECT COUNT(*) as count FROM _documents WHERE collection = ?`,\n [name]\n );\n\n const meta = metaResult.rows[0];\n const count = countResult.rows[0][0] as number;\n\n return {\n name,\n count,\n createdAt: meta[0] as string,\n lastModified: meta[1] as string\n };\n } catch (error) {\n console.error(`Failed to get stats for collection ${name}:`, error);\n return null;\n }\n }\n\n /**\n * Insert a document into a collection\n */\n async insert(collection: string, document: Document): Promise {\n await this.ensureInitialized();\n await this.createCollection(collection);\n\n try {\n const id = document.id || this.generateId();\n const timestamp = this.getTimestamp();\n const data = JSON.stringify(document);\n\n await sqlite.execute(\n `INSERT INTO _documents (id, collection, data, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`,\n [id, collection, data, timestamp, timestamp]\n );\n\n // Update collection last_modified\n await sqlite.execute(\n `UPDATE _collections_metadata SET last_modified = ? WHERE name = ?`,\n [timestamp, collection]\n );\n\n return { id, success: true };\n } catch (error) {\n console.error(`Failed to insert document into ${collection}:`, error);\n return { id: '', success: false };\n }\n }\n\n /**\n * Insert multiple documents\n */\n async insertMany(collection: string, documents: Document[]): Promise {\n const results: InsertResult[] = [];\n \n for (const doc of documents) {\n const result = await this.insert(collection, doc);\n results.push(result);\n }\n\n return results;\n }\n\n /**\n * Find documents in a collection\n */\n async find(collection: string, options: QueryOptions = {}): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(collection)) {\n return [];\n }\n\n try {\n let query = `SELECT data FROM _documents WHERE collection = ?`;\n const params: any[] = [collection];\n\n // Add WHERE conditions\n if (options.where) {\n // For now, we'll do simple field matching\n // In a more advanced implementation, you'd parse the where clause\n // and convert it to SQL WHERE conditions\n for (const [field, value] of Object.entries(options.where)) {\n query += ` AND JSON_EXTRACT(data, '$.${field}') = ?`;\n params.push(JSON.stringify(value));\n }\n }\n\n // Add sorting\n if (options.sort && options.sort.length > 0) {\n const sortClauses = options.sort.map(sort => \n `JSON_EXTRACT(data, '$.${sort.field}') ${sort.direction.toUpperCase()}`\n );\n query += ` ORDER BY ${sortClauses.join(', ')}`;\n }\n\n // Add pagination\n if (options.limit) {\n query += ` LIMIT ${options.limit}`;\n if (options.offset) {\n query += ` OFFSET ${options.offset}`;\n }\n }\n\n const result = await sqlite.execute(query, params);\n \n return result.rows.map(row => {\n try {\n return JSON.parse(row[0] as string);\n } catch (error) {\n console.error('Failed to parse document JSON:', error);\n return null;\n }\n }).filter(doc => doc !== null);\n } catch (error) {\n console.error(`Failed to find documents in ${collection}:`, error);\n return [];\n }\n }\n\n /**\n * Find a single document by ID\n */\n async findById(collection: string, id: string): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(collection)) {\n return null;\n }\n\n try {\n const result = await sqlite.execute(\n `SELECT data FROM _documents WHERE collection = ? AND id = ?`,\n [collection, id]\n );\n\n if (result.rows.length === 0) {\n return null;\n }\n\n return JSON.parse(result.rows[0][0] as string);\n } catch (error) {\n console.error(`Failed to find document ${id} in ${collection}:`, error);\n return null;\n }\n }\n\n /**\n * Update documents in a collection\n */\n async update(collection: string, where: Record, update: Partial): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(collection)) {\n return { modifiedCount: 0, success: false };\n }\n\n try {\n // First, find documents that match the where clause\n const documents = await this.find(collection, { where });\n \n if (documents.length === 0) {\n return { modifiedCount: 0, success: true };\n }\n\n let modifiedCount = 0;\n const timestamp = this.getTimestamp();\n\n for (const doc of documents) {\n if (!doc.id) continue;\n\n // Merge the update with the existing document\n const updatedDoc = { ...doc, ...update, id: doc.id };\n const data = JSON.stringify(updatedDoc);\n\n await sqlite.execute(\n `UPDATE _documents SET data = ?, updated_at = ? WHERE collection = ? AND id = ?`,\n [data, timestamp, collection, doc.id]\n );\n\n modifiedCount++;\n }\n\n // Update collection last_modified\n if (modifiedCount > 0) {\n await sqlite.execute(\n `UPDATE _collections_metadata SET last_modified = ? WHERE name = ?`,\n [timestamp, collection]\n );\n }\n\n return { modifiedCount, success: true };\n } catch (error) {\n console.error(`Failed to update documents in ${collection}:`, error);\n return { modifiedCount: 0, success: false };\n }\n }\n\n /**\n * Update a single document by ID\n */\n updateById(collection: string, id: string, update: Partial): Promise {\n return this.update(collection, { id }, update);\n }\n\n /**\n * Delete documents from a collection\n */\n async delete(collection: string, where: Record): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(collection)) {\n return { deletedCount: 0, success: false };\n }\n\n try {\n // First, find documents that match the where clause\n const documents = await this.find(collection, { where });\n \n if (documents.length === 0) {\n return { deletedCount: 0, success: true };\n }\n\n let deletedCount = 0;\n const timestamp = this.getTimestamp();\n\n for (const doc of documents) {\n if (!doc.id) continue;\n\n await sqlite.execute(\n `DELETE FROM _documents WHERE collection = ? AND id = ?`,\n [collection, doc.id]\n );\n\n deletedCount++;\n }\n\n // Update collection last_modified\n if (deletedCount > 0) {\n await sqlite.execute(\n `UPDATE _collections_metadata SET last_modified = ? WHERE name = ?`,\n [timestamp, collection]\n );\n }\n\n return { deletedCount, success: true };\n } catch (error) {\n console.error(`Failed to delete documents from ${collection}:`, error);\n return { deletedCount: 0, success: false };\n }\n }\n\n /**\n * Delete a single document by ID\n */\n deleteById(collection: string, id: string): Promise {\n return this.delete(collection, { id });\n }\n\n /**\n * Count documents in a collection\n */\n async count(collection: string, where?: Record): Promise {\n await this.ensureInitialized();\n\n if (!this.collections.has(collection)) {\n return 0;\n }\n\n try {\n let query = `SELECT COUNT(*) as count FROM _documents WHERE collection = ?`;\n const params: any[] = [collection];\n\n // Add WHERE conditions\n if (where) {\n for (const [field, value] of Object.entries(where)) {\n query += ` AND JSON_EXTRACT(data, '$.${field}') = ?`;\n params.push(JSON.stringify(value));\n }\n }\n\n const result = await sqlite.execute(query, params);\n return result.rows[0][0] as number;\n } catch (error) {\n console.error(`Failed to count documents in ${collection}:`, error);\n return 0;\n }\n }\n\n /**\n * Get database statistics\n */\n async getStats(): Promise<{ collections: number; totalDocuments: number; collectionsStats: CollectionStats[] }> {\n await this.ensureInitialized();\n\n try {\n const collections = await this.listCollections();\n const collectionsStats: CollectionStats[] = [];\n let totalDocuments = 0;\n\n for (const collection of collections) {\n const stats = await this.getCollectionStats(collection);\n if (stats) {\n collectionsStats.push(stats);\n totalDocuments += stats.count;\n }\n }\n\n return {\n collections: collections.length,\n totalDocuments,\n collectionsStats\n };\n } catch (error) {\n console.error('Failed to get database stats:', error);\n return { collections: 0, totalDocuments: 0, collectionsStats: [] };\n }\n }\n}\n\n// Export a default instance\nexport const jsonDb = new JsonDB();\n\n// Export the class for custom instances\nexport default JsonDB;\n",[],[199,215],{"_102":223,"_95":224,"_151":225,"_153":200,"_154":136,"_155":226,"_157":158,"_104":227,"_99":32,"_160":173,"_162":228,"_163":22,"_164":-5,"_165":229,"_98":230},"1d5743d0-9464-11f0-ae79-0224a6c84d84","migrations.ts","1d574498-9464-11f0-ae79-0224a6c84d84",4,["D",1758181815832],"/**\n * Migration utilities for JsonDB\n * Provides tools for managing database schema changes and data migrations\n */\n\nimport { sqlite } from \"https://esm.town/v/std/sqlite\";\n\nexport interface Migration {\n version: number;\n name: string;\n up: () => Promise;\n down: () => Promise;\n}\n\nexport interface MigrationResult {\n success: boolean;\n version: number;\n message: string;\n error?: string;\n}\n\nexport class MigrationManager {\n private migrations: Migration[] = [];\n private currentVersion: number = 0;\n\n constructor() {\n this.initialize();\n }\n\n /**\n * Initialize the migration system\n */\n private async initialize(): Promise {\n try {\n // Create migrations table\n await sqlite.execute(`\n CREATE TABLE IF NOT EXISTS _migrations (\n version INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n applied_at TEXT NOT NULL\n )\n `);\n\n // Get current version\n const result = await sqlite.execute(`\n SELECT MAX(version) as version FROM _migrations\n `);\n \n this.currentVersion = result.rows[0][0] as number || 0;\n } catch (error) {\n console.error('Failed to initialize migration system:', error);\n throw error;\n }\n }\n\n /**\n * Add a migration\n */\n addMigration(migration: Migration): void {\n this.migrations.push(migration);\n // Sort by version\n this.migrations.sort((a, b) => a.version - b.version);\n }\n\n /**\n * Get all available migrations\n */\n getMigrations(): Migration[] {\n return [...this.migrations];\n }\n\n /**\n * Get current database version\n */\n getCurrentVersion(): number {\n return this.currentVersion;\n }\n\n /**\n * Get pending migrations\n */\n getPendingMigrations(): Migration[] {\n return this.migrations.filter(m => m.version > this.currentVersion);\n }\n\n /**\n * Run all pending migrations\n */\n async migrate(): Promise {\n const results: MigrationResult[] = [];\n const pending = this.getPendingMigrations();\n\n for (const migration of pending) {\n try {\n await migration.up();\n \n // Record the migration\n await sqlite.execute(`\n INSERT INTO _migrations (version, name, applied_at) VALUES (?, ?, ?)\n `, [migration.version, migration.name, new Date().toISOString()]);\n\n this.currentVersion = migration.version;\n\n results.push({\n success: true,\n version: migration.version,\n message: `Migration ${migration.name} applied successfully`\n });\n\n console.log(`✅ Migration ${migration.name} (v${migration.version}) applied`);\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : 'Unknown error';\n \n results.push({\n success: false,\n version: migration.version,\n message: `Migration ${migration.name} failed`,\n error: errorMessage\n });\n\n console.error(`❌ Migration ${migration.name} (v${migration.version}) failed:`, error);\n \n // Stop on first failure\n break;\n }\n }\n\n return results;\n }\n\n /**\n * Rollback to a specific version\n */\n async rollback(targetVersion: number): Promise {\n const results: MigrationResult[] = [];\n const migrationsToRollback = this.migrations\n .filter(m => m.version > targetVersion && m.version <= this.currentVersion)\n .sort((a, b) => b.version - a.version); // Reverse order for rollback\n\n for (const migration of migrationsToRollback) {\n try {\n await migration.down();\n \n // Remove the migration record\n await sqlite.execute(`\n DELETE FROM _migrations WHERE version = ?\n `, [migration.version]);\n\n this.currentVersion = migration.version - 1;\n\n results.push({\n success: true,\n version: migration.version,\n message: `Migration ${migration.name} rolled back successfully`\n });\n\n console.log(`↩️ Migration ${migration.name} (v${migration.version}) rolled back`);\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : 'Unknown error';\n \n results.push({\n success: false,\n version: migration.version,\n message: `Failed to rollback migration ${migration.name}`,\n error: errorMessage\n });\n\n console.error(`❌ Rollback of ${migration.name} (v${migration.version}) failed:`, error);\n \n // Stop on first failure\n break;\n }\n }\n\n return results;\n }\n\n /**\n * Reset database (rollback all migrations)\n */\n reset(): Promise {\n return this.rollback(0);\n }\n\n /**\n * Get migration history\n */\n async getHistory(): Promise> {\n try {\n const result = await sqlite.execute(`\n SELECT version, name, applied_at FROM _migrations ORDER BY version ASC\n `);\n\n return result.rows.map(row => ({\n version: row[0] as number,\n name: row[1] as string,\n applied_at: row[2] as string\n }));\n } catch (error) {\n console.error('Failed to get migration history:', error);\n return [];\n }\n }\n\n /**\n * Check if database is up to date\n */\n isUpToDate(): boolean {\n return this.getPendingMigrations().length === 0;\n }\n}\n\n// Predefined migrations for JsonDB\nexport const createDefaultMigrations = (): Migration[] => [\n {\n version: 1,\n name: \"create_collections_metadata\",\n up: async () => {\n await sqlite.execute(`\n CREATE TABLE IF NOT EXISTS _collections_metadata (\n name TEXT PRIMARY KEY,\n created_at TEXT NOT NULL,\n last_modified TEXT NOT NULL,\n schema_version INTEGER DEFAULT 1\n )\n `);\n },\n down: async () => {\n await sqlite.execute(`DROP TABLE IF EXISTS _collections_metadata`);\n }\n },\n {\n version: 2,\n name: \"create_documents_table\",\n up: async () => {\n await sqlite.execute(`\n CREATE TABLE IF NOT EXISTS _documents (\n id TEXT PRIMARY KEY,\n collection TEXT NOT NULL,\n data TEXT NOT NULL,\n created_at TEXT NOT NULL,\n updated_at TEXT NOT NULL,\n FOREIGN KEY (collection) REFERENCES _collections_metadata(name)\n )\n `);\n },\n down: async () => {\n await sqlite.execute(`DROP TABLE IF EXISTS _documents`);\n }\n },\n {\n version: 3,\n name: \"create_indexes\",\n up: async () => {\n await sqlite.execute(`\n CREATE INDEX IF NOT EXISTS idx_documents_collection ON _documents(collection)\n `);\n await sqlite.execute(`\n CREATE INDEX IF NOT EXISTS idx_documents_created_at ON _documents(created_at)\n `);\n },\n down: async () => {\n await sqlite.execute(`DROP INDEX IF EXISTS idx_documents_collection`);\n await sqlite.execute(`DROP INDEX IF EXISTS idx_documents_created_at`);\n }\n },\n {\n version: 4,\n name: \"add_json_extract_indexes\",\n up: async () => {\n // Add indexes for common JSON field queries\n await sqlite.execute(`\n CREATE INDEX IF NOT EXISTS idx_documents_json_name \n ON _documents(JSON_EXTRACT(data, '$.name'))\n `);\n await sqlite.execute(`\n CREATE INDEX IF NOT EXISTS idx_documents_json_email \n ON _documents(JSON_EXTRACT(data, '$.email'))\n `);\n },\n down: async () => {\n await sqlite.execute(`DROP INDEX IF EXISTS idx_documents_json_name`);\n await sqlite.execute(`DROP INDEX IF EXISTS idx_documents_json_email`);\n }\n }\n];\n\n// Export a default migration manager with default migrations\nexport const migrationManager = new MigrationManager();\n\n// Add default migrations\ncreateDefaultMigrations().forEach(migration => {\n migrationManager.addMigration(migration);\n});\n\nexport default MigrationManager;\n",[],[199,224],[199],{"_102":233,"_95":234,"_151":235,"_153":-5,"_154":136,"_155":135,"_157":158,"_104":236,"_99":32,"_160":237,"_162":238,"_163":22,"_164":-5,"_165":239,"_98":240},"1eb0c90e-9464-11f0-a007-0224a6c84d84",".vtignore","1eb0c9ea-9464-11f0-a007-0224a6c84d84",["D",1758181815811],"file",".git\n.DS_Store\nnode_modules\nvendor",[],[234],{"_102":242,"_95":243,"_151":244,"_153":-5,"_154":136,"_155":245,"_157":158,"_104":246,"_99":32,"_160":237,"_162":247,"_163":22,"_164":-5,"_165":248,"_98":249},"1d5d2c5a-9464-11f0-b870-0224a6c84d84","AGENTS.md","1d5d2d36-9464-11f0-b870-0224a6c84d84",5,["D",1758181815838],"You are an advanced assistant specialized in generating Val Town code.\n\n## Core Guidelines\n\n- Ask clarifying questions when requirements are ambiguous\n- Provide complete, functional solutions rather than skeleton implementations\n- Test your logic against edge cases before presenting the final solution\n- Ensure all code follows Val Town's specific platform requirements\n- If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents\n\n## Code Standards\n\n- Generate code in TypeScript or TSX\n- Add appropriate TypeScript types and interfaces for all data structures\n- Prefer official SDKs or libraries than writing API calls directly\n- Ask the user to supply API or library documentation if you are at all unsure about it\n- **Never bake in secrets into the code** - always use environment variables\n- Include comments explaining complex logic (avoid commenting obvious operations)\n- Follow modern ES6+ conventions and functional programming practices if possible\n\n## Types of triggers\n\n### 1. HTTP Trigger\n\n- Create web APIs and endpoints\n- Handle HTTP requests and responses\n- Example structure:\n\n```ts\nexport default async function (req: Request) {\n return new Response(\"Hello World\");\n}\n```\n\nFiles that are HTTP triggers have http in their name like `foobar.http.tsx`\n\n### 2. Cron Triggers\n\n- Run on a schedule\n- Use cron expressions for timing\n- Example structure:\n\n```ts\nexport default async function () {\n // Scheduled task code\n}\n```\n\nFiles that are Cron triggers have cron in their name like `foobar.cron.tsx`\n\n### 3. Email Triggers\n\n- Process incoming emails\n- Handle email-based workflows\n- Example structure:\n\n```ts\nexport default async function (email: Email) {\n // Process email\n}\n```\n\nFiles that are Email triggers have email in their name like `foobar.email.tsx`\n\n\n## Val Town Standard Libraries\n\nVal Town provides several hosted services and utility functions.\n\n### Blob Storage\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\nawait blob.setJSON(\"myKey\", { hello: \"world\" });\nlet blobDemo = await blob.getJSON(\"myKey\");\nlet appKeys = await blob.list(\"app_\");\nawait blob.delete(\"myKey\");\n```\n\n### SQLite\n\n```ts\nimport { sqlite } from \"https://esm.town/v/std/sqlite\";\nconst TABLE_NAME = 'todo_app_users_2';\n// Create table - do this before usage and change table name when modifying schema\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL\n)`);\n// Query data\nconst result = await sqlite.execute(`SELECT * FROM ${TABLE_NAME} WHERE id = ?`, [1]);\n```\n\nNote: When changing a SQLite table's schema, change the table's name (e.g., add _2 or _3) to create a fresh table.\n\n### OpenAI\n\n```ts\nimport { OpenAI } from \"https://esm.town/v/std/openai\";\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n messages: [\n { role: \"user\", content: \"Say hello in a creative way\" },\n ],\n model: \"gpt-4o-mini\",\n max_tokens: 30,\n});\n```\n\n### Email\n\n```ts\nimport { email } from \"https://esm.town/v/std/email\";\n// By default emails the owner of the val\nawait email({ \n subject: \"Hi\", \n text: \"Hi\", \n html: \"

Hi

\"\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\" urls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.\nIf you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page\nor by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})` instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use: `

`\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified\n- **View Source:** Add a view source link by importing & using `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add `` to HTML to capture client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same version\n- **Styling:** Default to using TailwindCSS via `` unless otherwise specified\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n```\n├── backend/\n│ ├── database/\n│ │ ├── migrations.ts # Schema definitions\n│ │ ├── queries.ts # DB query functions\n│ │ └── README.md\n│ └── routes/ # Route modules\n│ ├── [route].ts\n│ └── static.ts # Static file serving\n│ ├── index.ts # Main entry point\n│ └── README.md\n├── frontend/\n│ ├── components/\n│ │ ├── App.tsx\n│ │ └── [Component].tsx\n│ ├── favicon.svg\n│ ├── index.html # Main HTML template\n│ ├── index.tsx # Frontend JS entry point\n│ ├── README.md\n│ └── style.css\n├── README.md\n└── shared/\n ├── README.md\n └── utils.ts # Shared types and functions\n```\n\n### Backend (Hono) Best Practices\n\n- Hono is the recommended API framework\n- Main entry point should be `backend/index.ts`\n- **Static asset serving:** Use the utility functions to read and serve project files:\n ```ts\n import { readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n \n // serve all files in frontend/ and shared/\n app.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\n app.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n \n // For index.html, often you'll want to bootstrap with initial data\n app.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n \n // Inject data to avoid extra round-trips\n const initialData = await fetchInitialData();\n const dataScript = ``;\n \n html = html.replace(\"\", `${dataScript}`);\n return c.html(html);\n });\n ```\n- Create RESTful API routes for CRUD operations\n- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:\n ```ts\n // Unwrap Hono errors to see original error details\n app.onError((err, c) => {\n throw err;\n });\n ```\n\n### Database Patterns\n- Run migrations on startup or comment out for performance\n- Change table names when modifying schemas rather than altering\n- Export clear query functions with proper TypeScript typing\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:** \n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`\n\n",[],[243],{"_102":251,"_95":252,"_151":253,"_153":-5,"_154":136,"_155":254,"_157":158,"_104":255,"_99":32,"_160":237,"_162":256,"_163":22,"_164":-5,"_165":257,"_98":258},"1d839dc2-9464-11f0-81f5-0224a6c84d84","README.md","1d839e6c-9464-11f0-81f5-0224a6c84d84",9,["D",1758181815802],"# JsonDB - A Document Database for Val Town\n\nJsonDB is a powerful document database library that provides a MongoDB-like interface over Val Town's SQLite. It abstracts away the complexity of SQL while maintaining the reliability and performance of SQLite.\n\n## Features\n\n- 🚀 **Document-based**: Store and query JSON documents like MongoDB\n- 🔍 **Powerful Queries**: Filter, sort, and paginate your data\n- 📊 **Collection Management**: Create, drop, and manage collections\n- 🔄 **Migrations**: Built-in migration system for schema changes\n- 🌐 **REST API**: Ready-to-use HTTP endpoints for Val Town\n- 📈 **Statistics**: Get insights into your database usage\n- 🛡️ **TypeScript**: Full TypeScript support with type safety\n\n## Quick Start\n\n### Basic Usage\n\n```typescript\nimport { jsonDb } from \"./src/json-db.ts\";\n\n// Create a collection and insert a document\nconst user = await jsonDb.insert(\"users\", {\n name: \"John Doe\",\n email: \"john@example.com\",\n age: 30,\n preferences: {\n theme: \"dark\",\n notifications: true\n }\n});\n\n// Find documents\nconst users = await jsonDb.find(\"users\", {\n where: { age: { $gte: 25 } },\n sort: [{ field: \"name\", direction: \"asc\" }],\n limit: 10\n});\n\n// Update documents\nawait jsonDb.updateById(\"users\", user.id, {\n age: 31,\n preferences: { theme: \"light\" }\n});\n\n// Delete documents\nawait jsonDb.deleteById(\"users\", user.id);\n```\n\n### Collection Management\n\n```typescript\n// Create a collection\nawait jsonDb.createCollection(\"products\");\n\n// List all collections\nconst collections = await jsonDb.listCollections();\n\n// Get collection statistics\nconst stats = await jsonDb.getCollectionStats(\"users\");\n\n// Drop a collection\nawait jsonDb.dropCollection(\"old_collection\");\n```\n\n### Advanced Queries\n\n```typescript\n// Find with complex filtering\nconst results = await jsonDb.find(\"products\", {\n where: {\n category: \"electronics\",\n price: { $lt: 500 },\n inStock: true\n },\n sort: [\n { field: \"price\", direction: \"asc\" },\n { field: \"name\", direction: \"desc\" }\n ],\n limit: 20,\n offset: 0\n});\n\n// Count documents\nconst count = await jsonDb.count(\"products\", {\n category: \"electronics\"\n});\n\n// Batch operations\nconst products = [\n { name: \"Laptop\", price: 999.99, category: \"electronics\" },\n { name: \"Mouse\", price: 29.99, category: \"electronics\" }\n];\n\nawait jsonDb.insertMany(\"products\", products);\n```\n\n## REST API\n\nJsonDB includes a complete REST API for Val Town. Use the HTTP example to create endpoints:\n\n```typescript\n// GET /collections/users/documents\n// POST /collections/users/documents\n// PUT /collections/users/documents/:id\n// DELETE /collections/users/documents/:id\n```\n\n### API Endpoints\n\n- `GET /health` - Health check\n- `GET /stats` - Database statistics\n- `GET /collections` - List collections\n- `POST /collections` - Create collection\n- `DELETE /collections/:name` - Delete collection\n- `GET /collections/:name/documents` - Find documents\n- `POST /collections/:name/documents` - Create document\n- `GET /collections/:name/documents/:id` - Get document by ID\n- `PUT /collections/:name/documents/:id` - Update document\n- `DELETE /collections/:name/documents/:id` - Delete document\n\n## Migrations\n\nJsonDB includes a powerful migration system:\n\n```typescript\nimport { migrationManager } from \"./src/migrations.ts\";\n\n// Add a custom migration\nmigrationManager.addMigration({\n version: 5,\n name: \"add_user_roles\",\n up: async () => {\n // Add new fields or tables\n await sqlite.execute(`\n ALTER TABLE _documents \n ADD COLUMN role TEXT DEFAULT 'user'\n `);\n },\n down: async () => {\n // Rollback changes\n await sqlite.execute(`\n ALTER TABLE _documents \n DROP COLUMN role\n `);\n }\n});\n\n// Run migrations\nconst results = await migrationManager.migrate();\n\n// Rollback to specific version\nawait migrationManager.rollback(3);\n```\n\n## Examples\n\nCheck out the `examples/` directory for complete examples:\n\n- `basic-usage.ts` - Core functionality examples\n- `val-town-http.ts` - REST API implementation\n\n## API Reference\n\n### JsonDB Class\n\n#### Collection Management\n- `createCollection(name: string): Promise`\n- `dropCollection(name: string): Promise`\n- `listCollections(): Promise`\n- `getCollectionStats(name: string): Promise`\n\n#### Document Operations\n- `insert(collection: string, document: Document): Promise`\n- `insertMany(collection: string, documents: Document[]): Promise`\n- `find(collection: string, options?: QueryOptions): Promise`\n- `findById(collection: string, id: string): Promise`\n- `update(collection: string, where: Record, update: Partial): Promise`\n- `updateById(collection: string, id: string, update: Partial): Promise`\n- `delete(collection: string, where: Record): Promise`\n- `deleteById(collection: string, id: string): Promise`\n- `count(collection: string, where?: Record): Promise`\n\n#### Database Management\n- `getStats(): Promise<{ collections: number; totalDocuments: number; collectionsStats: CollectionStats[] }>`\n\n### Types\n\n```typescript\ninterface Document {\n id?: string;\n [key: string]: any;\n}\n\ninterface QueryOptions {\n limit?: number;\n offset?: number;\n sort?: { field: string; direction: 'asc' | 'desc' }[];\n where?: Record;\n}\n\ninterface CollectionStats {\n name: string;\n count: number;\n createdAt: string;\n lastModified: string;\n}\n```\n\n## Installation\n\n1. Copy the `src/` directory to your Val Town project\n2. Import and use:\n\n```typescript\nimport { jsonDb } from \"./src/json-db.ts\";\n```\n\n## Val Town Integration\n\nJsonDB is specifically designed for Val Town and uses:\n- Val Town's SQLite standard library\n- Proper error handling for serverless environment\n- TypeScript support with Val Town types\n- REST API patterns for HTTP vals\n\n## Performance Tips\n\n1. **Use indexes**: The migration system creates indexes for common fields\n2. **Batch operations**: Use `insertMany()` for multiple documents\n3. **Pagination**: Use `limit` and `offset` for large datasets\n4. **Collection cleanup**: Drop unused collections to save space\n\n## Limitations\n\n- JSON field queries are limited to simple equality matching\n- Complex aggregation queries require custom SQL\n- No built-in full-text search (can be added via migrations)\n- Document size limited by SQLite's TEXT storage\n\n## Contributing\n\nThis library is designed for Val Town projects. Feel free to extend it with additional features or optimizations specific to your use case.\n\n## License\n\nMIT License - feel free to use in your Val Town projects!\n\n",[],[252],{"_102":260,"_95":261,"_151":262,"_153":-5,"_154":136,"_155":263,"_157":158,"_104":264,"_99":32,"_160":237,"_162":265,"_163":22,"_164":-5,"_165":266,"_98":267},"1d60407a-9464-11f0-a12c-0224a6c84d84","deno.json","1d60416a-9464-11f0-a12c-0224a6c84d84",6,["D",1758181815808],"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\n \"https://www.val.town/types/valtown.d.ts\"\n ],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"files\": {\n \"include\": [\n \"deno:/https/esm.town/**/*\"\n ]\n },\n \"rules\": {\n \"exclude\": [\n \"no-explicit-any\"\n ]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[],[261],{"_102":269,"_95":270,"_151":271,"_153":-5,"_154":136,"_155":272,"_157":158,"_104":273,"_99":32,"_160":173,"_162":274,"_163":22,"_164":-5,"_165":275,"_98":276},"1d53d2f4-9464-11f0-9551-0224a6c84d84","test.ts","1d53d3c6-9464-11f0-9551-0224a6c84d84",3,["D",1758181815799],"/**\n * Test file for JsonDB\n * Run this to verify the library works correctly\n */\n\nimport { jsonDb } from \"./src/json-db.ts\";\n\nasync function runTests() {\n console.log(\"🧪 Starting JsonDB tests...\\n\");\n\n try {\n // Test 1: Collection Management\n console.log(\"1️⃣ Testing collection management...\");\n await jsonDb.createCollection(\"test_users\");\n const collections = await jsonDb.listCollections();\n console.log(\"✅ Collections:\", collections);\n console.log(\"✅ Collection 'test_users' created\\n\");\n\n // Test 2: Document Insertion\n console.log(\"2️⃣ Testing document insertion...\");\n const user1 = await jsonDb.insert(\"test_users\", {\n name: \"Alice Johnson\",\n email: \"alice@example.com\",\n age: 28,\n role: \"admin\",\n preferences: {\n theme: \"dark\",\n notifications: true\n }\n });\n console.log(\"✅ User 1 inserted:\", user1);\n\n const user2 = await jsonDb.insert(\"test_users\", {\n name: \"Bob Smith\",\n email: \"bob@example.com\",\n age: 32,\n role: \"user\",\n preferences: {\n theme: \"light\",\n notifications: false\n }\n });\n console.log(\"✅ User 2 inserted:\", user2);\n\n const user3 = await jsonDb.insert(\"test_users\", {\n name: \"Charlie Brown\",\n email: \"charlie@example.com\",\n age: 25,\n role: \"user\",\n preferences: {\n theme: \"dark\",\n notifications: true\n }\n });\n console.log(\"✅ User 3 inserted:\", user3);\n console.log(\"\");\n\n // Test 3: Document Retrieval\n console.log(\"3️⃣ Testing document retrieval...\");\n const allUsers = await jsonDb.find(\"test_users\");\n console.log(\"✅ All users:\", allUsers.length, \"found\");\n\n const foundUser = await jsonDb.findById(\"test_users\", user1.id);\n console.log(\"✅ Found user by ID:\", foundUser?.name);\n\n const adminUsers = await jsonDb.find(\"test_users\", {\n where: { role: \"admin\" }\n });\n console.log(\"✅ Admin users:\", adminUsers.length, \"found\");\n console.log(\"\");\n\n // Test 4: Document Updates\n console.log(\"4️⃣ Testing document updates...\");\n const updateResult = await jsonDb.updateById(\"test_users\", user2.id, {\n age: 33,\n preferences: { theme: \"dark\" }\n });\n console.log(\"✅ Update result:\", updateResult);\n\n const updatedUser = await jsonDb.findById(\"test_users\", user2.id);\n console.log(\"✅ Updated user age:\", updatedUser?.age);\n console.log(\"✅ Updated user theme:\", updatedUser?.preferences?.theme);\n console.log(\"\");\n\n // Test 5: Querying and Sorting\n console.log(\"5️⃣ Testing queries and sorting...\");\n const sortedUsers = await jsonDb.find(\"test_users\", {\n sort: [{ field: \"age\", direction: \"asc\" }]\n });\n console.log(\"✅ Users sorted by age:\", sortedUsers.map(u => `${u.name} (${u.age})`));\n\n const darkThemeUsers = await jsonDb.find(\"test_users\", {\n where: { \"preferences.theme\": \"dark\" }\n });\n console.log(\"✅ Dark theme users:\", darkThemeUsers.length, \"found\");\n console.log(\"\");\n\n // Test 6: Counting and Statistics\n console.log(\"6️⃣ Testing counting and statistics...\");\n const totalCount = await jsonDb.count(\"test_users\");\n console.log(\"✅ Total users:\", totalCount);\n\n const userCount = await jsonDb.count(\"test_users\", { role: \"user\" });\n console.log(\"✅ Regular users:\", userCount);\n\n const stats = await jsonDb.getCollectionStats(\"test_users\");\n console.log(\"✅ Collection stats:\", stats);\n console.log(\"\");\n\n // Test 7: Batch Operations\n console.log(\"7️⃣ Testing batch operations...\");\n const newUsers = [\n { name: \"Diana Prince\", email: \"diana@example.com\", age: 30, role: \"user\" },\n { name: \"Eve Wilson\", email: \"eve@example.com\", age: 27, role: \"admin\" }\n ];\n const batchResults = await jsonDb.insertMany(\"test_users\", newUsers);\n console.log(\"✅ Batch insert results:\", batchResults.filter(r => r.success).length, \"successful\");\n console.log(\"\");\n\n // Test 8: Pagination\n console.log(\"8️⃣ Testing pagination...\");\n const page1 = await jsonDb.find(\"test_users\", { limit: 2, offset: 0 });\n const page2 = await jsonDb.find(\"test_users\", { limit: 2, offset: 2 });\n console.log(\"✅ Page 1:\", page1.length, \"users\");\n console.log(\"✅ Page 2:\", page2.length, \"users\");\n console.log(\"\");\n\n // Test 9: Document Deletion\n console.log(\"9️⃣ Testing document deletion...\");\n const deleteResult = await jsonDb.deleteById(\"test_users\", user3.id);\n console.log(\"✅ Delete result:\", deleteResult);\n\n const remainingCount = await jsonDb.count(\"test_users\");\n console.log(\"✅ Remaining users after deletion:\", remainingCount);\n console.log(\"\");\n\n // Test 10: Database Statistics\n console.log(\"🔟 Testing database statistics...\");\n const dbStats = await jsonDb.getStats();\n console.log(\"✅ Database stats:\", dbStats);\n console.log(\"\");\n\n // Test 11: Error Handling\n console.log(\"1️⃣1️⃣ Testing error handling...\");\n const nonExistent = await jsonDb.findById(\"test_users\", \"non-existent-id\");\n console.log(\"✅ Non-existent document:\", nonExistent);\n\n const nonExistentCollection = await jsonDb.find(\"non_existent_collection\");\n console.log(\"✅ Non-existent collection query:\", nonExistentCollection.length, \"documents\");\n console.log(\"\");\n\n // Cleanup\n console.log(\"🧹 Cleaning up test data...\");\n await jsonDb.dropCollection(\"test_users\");\n console.log(\"✅ Test collection dropped\");\n\n console.log(\"\\n🎉 All tests completed successfully!\");\n console.log(\"JsonDB is working correctly! 🚀\");\n\n } catch (error) {\n console.error(\"❌ Test failed:\", error);\n throw error;\n }\n}\n\n// Run tests if this file is executed directly\nif (import.meta.main) {\n runTests().catch(console.error);\n}\n\nexport { runTests };\n\n",[],[270],"files",[148,167,177,187,197,204,213,222,232,241,250,259,268],"counts",{"_281":32,"_282":156,"_283":32,"_284":285},"pulls","branches","forks","envVars",{"_286":32,"_287":32},"count","emptyCount","contents",[290,293,296,299,302,305,308],{"_102":149,"_95":150,"_151":152,"_153":-5,"_154":136,"_155":156,"_157":158,"_104":291,"_99":32,"_160":161,"_162":-5,"_163":22,"_164":-5,"_98":292},["D",1758181815221],[150],{"_102":198,"_95":199,"_151":200,"_153":-5,"_154":136,"_155":201,"_157":158,"_104":294,"_99":32,"_160":161,"_162":-5,"_163":22,"_164":-5,"_98":295},["D",1758181815414],[199],{"_102":233,"_95":234,"_151":235,"_153":-5,"_154":136,"_155":135,"_157":158,"_104":297,"_99":32,"_160":237,"_162":238,"_163":22,"_164":-5,"_98":298},["D",1758181815811],[234],{"_102":242,"_95":243,"_151":244,"_153":-5,"_154":136,"_155":245,"_157":158,"_104":300,"_99":32,"_160":237,"_162":247,"_163":22,"_164":-5,"_98":301},["D",1758181815838],[243],{"_102":251,"_95":252,"_151":253,"_153":-5,"_154":136,"_155":254,"_157":158,"_104":303,"_99":32,"_160":237,"_162":256,"_163":22,"_164":-5,"_98":304},["D",1758181815802],[252],{"_102":260,"_95":261,"_151":262,"_153":-5,"_154":136,"_155":263,"_157":158,"_104":306,"_99":32,"_160":237,"_162":265,"_163":22,"_164":-5,"_98":307},["D",1758181815808],[261],{"_102":269,"_95":270,"_151":271,"_153":-5,"_154":136,"_155":272,"_157":158,"_104":309,"_99":32,"_160":173,"_162":274,"_163":22,"_164":-5,"_98":310},["D",1758181815799],[270],"upstreamProject","upstreamBranch","emptyEnvVars","isNew","flags",[],"routes/_app.x.$handle.$name.environment-variables",{"_93":94,"_95":96,"_100":319,"_284":324},{"_102":103,"_95":96,"_104":320,"_106":-5,"_107":22,"_108":109,"_110":72,"_111":-5,"_14":112,"_113":-5,"_114":22,"_115":-5,"_116":32,"_16":117,"_118":119,"_120":119,"_121":122,"_123":122,"_124":122,"_125":119,"_126":119,"_23":321,"_130":322,"_133":323,"_145":22},["D",1758130324008],{"_93":94,"_128":129},{"_93":94,"_132":129},{"_99":135,"_95":43,"_102":136,"_137":103,"_138":-5,"_139":-5,"_140":-5,"_141":-5,"_142":-5,"_143":96,"_144":94},[],"actionData","errors"]

wilhelm

json-db

Environment variables