@joystick.js/db-canary 0.0.0-canary.2209

package/prompts/TYPESCRIPT_GENERATION.md

@@ -0,0 +1,179 @@
+# TypeScript Definition Generation from JSDoc
+
+This document explains how to generate TypeScript definition files (.d.ts) from the JSDoc comments in the JoystickDB project.
+
+## Prerequisites
+
+Make sure you have TypeScript installed as a dev dependency:
+
+```bash
+npm install --save-dev typescript
+```
+
+## Configuration Files
+
+### tsconfig.json
+The TypeScript configuration file is set up to:
+- Allow JavaScript files (`allowJs: true`)
+- Generate only declaration files (`emitDeclarationOnly: true`)
+- Output to the `./types` directory
+- Include all files in `src/**/*.js`
+- Exclude test files and node_modules
+
+### package.json Scripts
+Three npm scripts are available for type generation:
+
+```json
+{
+  "build:types": "tsc --declaration --emitDeclarationOnly --allowJs --outDir types src/**/*.js",
+  "build:types:client": "tsc --declaration --emitDeclarationOnly --allowJs --outDir types/client src/client/*.js",
+  "build:types:server": "tsc --declaration --emitDeclarationOnly --allowJs --outDir types/server src/server/**/*.js"
+}
+```
+
+## Generating TypeScript Definitions
+
+### Generate All Types
+```bash
+npm run build:types
+```
+
+### Generate Client Types Only
+```bash
+npm run build:types:client
+```
+
+### Generate Server Types Only
+```bash
+npm run build:types:server
+```
+
+### Manual Generation
+You can also run TypeScript compiler directly:
+
+```bash
+# Generate all types
+npx tsc
+
+# Generate specific files
+npx tsc --declaration --emitDeclarationOnly --allowJs --outDir types src/client/index.js
+```
+
+## Output Structure
+
+After running the type generation, you'll find the TypeScript definition files in the `types/` directory:
+
+```
+types/
+├── client/
+│   └── index.d.ts          # Client library types
+└── server/
+    ├── index.d.ts          # Main server types
+    ├── cluster/
+    │   ├── index.d.ts      # Cluster management types
+    │   └── master.d.ts     # Cluster master types
+    └── lib/
+        ├── logger.d.ts     # Logger types
+        ├── tcp_protocol.d.ts # TCP protocol types
+        └── operations/
+            ├── insert_one.d.ts  # Insert operation types
+            ├── find_one.d.ts    # Find operation types
+            └── ...              # Other operation types
+```
+
+## Using the Generated Types
+
+### In TypeScript Projects
+```typescript
+import { JoystickDBClient, ClientOptions } from './types/client/index.js';
+
+const client: JoystickDBClient = joystickdb.client({
+  host: 'localhost',
+  port: 1983,
+  authentication: {
+    password: 'your-password'
+  }
+});
+```
+
+### In JavaScript Projects with JSDoc
+```javascript
+/**
+ * @typedef {import('./types/client/index.js').ClientOptions} ClientOptions
+ * @typedef {import('./types/client/index.js').JoystickDBClient} JoystickDBClient
+ */
+
+/** @type {ClientOptions} */
+const options = {
+  host: 'localhost',
+  port: 1983
+};
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"No inputs were found" error**: Make sure your JavaScript files have proper JSDoc comments and are in the correct directories.
+
+2. **Import/Export issues**: Ensure your JavaScript files use proper ES module syntax (`import`/`export`).
+
+3. **Missing types**: Check that your JSDoc comments use proper syntax:
+   - `@param {Type} name - description`
+   - `@returns {Type} description`
+   - `@typedef {Object} TypeName`
+
+### Validating Generated Types
+
+You can validate the generated types by creating a test TypeScript file:
+
+```typescript
+// test-types.ts
+import { JoystickDBClient } from './types/client/index.js';
+
+// This should compile without errors if types are correct
+const client = new JoystickDBClient({
+  host: 'localhost',
+  port: 1983
+});
+```
+
+Then compile it:
+```bash
+npx tsc test-types.ts --noEmit
+```
+
+## Continuous Integration
+
+Add type generation to your CI/CD pipeline:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Generate TypeScript definitions
+  run: npm run build:types
+
+- name: Validate generated types
+  run: npx tsc --noEmit types/**/*.d.ts
+```
+
+## Updating Types
+
+When you modify JSDoc comments in your source files:
+
+1. Run the type generation script again
+2. Commit the updated `.d.ts` files to version control
+3. Update version numbers if publishing to npm
+
+## Publishing Types
+
+If publishing to npm, include the types in your package.json:
+
+```json
+{
+  "main": "src/server/index.js",
+  "types": "types/server/index.d.ts",
+  "files": [
+    "src/",
+    "types/"
+  ]
+}

package/src/client/database.js

@@ -0,0 +1,166 @@
+/**
+ * Database interface for method chaining operations.
+ * Provides a fluent API for database-level operations and collection access.
+ */
+class Database {
+  /**
+   * Creates a new Database instance.
+   * @param {JoystickDBClient} client - The client instance
+   * @param {string} database_name - Name of the database
+   */
+  constructor(client, database_name) {
+    this.client = client;
+    this.database_name = database_name;
+  }
+  
+  /**
+   * Returns a collection interface for method chaining operations.
+   * @param {string} collection_name - Collection name
+   * @returns {Collection} Collection interface instance
+   */
+  collection(collection_name) {
+    // NOTE: Import Collection class dynamically to avoid circular dependency.
+    const Collection = this.client.constructor.Collection;
+    return new Collection(this.client, this.database_name, collection_name);
+  }
+  
+  /**
+   * Lists all collections in the database.
+   * @returns {Promise<Object>} Collections list
+   */
+  async list_collections() {
+    return this.client.send_request('admin', { 
+      admin_action: 'list_collections',
+      database: this.database_name
+    });
+  }
+  
+  /**
+   * Gets database-specific statistics.
+   * @returns {Promise<Object>} Database statistics
+   */
+  async get_stats() {
+    return this.client.send_request('admin', { 
+      admin_action: 'get_database_stats',
+      database: this.database_name
+    });
+  }
+  
+  /**
+   * Drops the entire database (admin operation).
+   * @returns {Promise<Object>} Drop database result
+   */
+  async drop_database() {
+    return this.client.send_request('admin', { 
+      admin_action: 'drop_database',
+      database: this.database_name
+    });
+  }
+  
+  /**
+   * Explicitly creates a collection in the database.
+   * @param {string} collection_name - Name of collection to create
+   * @param {Object} [options={}] - Collection creation options
+   * @returns {Promise<Object>} Create collection result
+   */
+  async create_collection(collection_name, options = {}) {
+    return this.client.send_request('admin', { 
+      admin_action: 'create_collection',
+      database: this.database_name,
+      collection: collection_name,
+      options
+    });
+  }
+  
+  /**
+   * Lists all documents in a collection (admin operation).
+   * @param {string} collection_name - Name of collection
+   * @returns {Promise<Object>} List documents result
+   */
+  async list_documents(collection_name) {
+    return this.client.send_request('admin', { 
+      admin_action: 'list_documents',
+      database: this.database_name,
+      collection: collection_name
+    });
+  }
+  
+  /**
+   * Gets a specific document by ID (admin operation).
+   * @param {string} collection_name - Name of collection
+   * @param {string} document_id - Document ID
+   * @returns {Promise<Object>} Get document result
+   */
+  async get_document(collection_name, document_id) {
+    return this.client.send_request('admin', { 
+      admin_action: 'get_document',
+      database: this.database_name,
+      collection: collection_name,
+      document_id
+    });
+  }
+  
+  /**
+   * Queries documents in a collection (admin operation).
+   * @param {string} collection_name - Name of collection
+   * @param {Object} filter - Query filter
+   * @returns {Promise<Object>} Query documents result
+   */
+  async query_documents(collection_name, filter) {
+    return this.client.send_request('admin', { 
+      admin_action: 'query_documents',
+      database: this.database_name,
+      collection: collection_name,
+      filter
+    });
+  }
+  
+  /**
+   * Inserts a document into a collection (admin operation).
+   * @param {string} collection_name - Name of collection
+   * @param {Object} document - Document to insert
+   * @returns {Promise<Object>} Insert document result
+   */
+  async insert_document(collection_name, document) {
+    return this.client.send_request('admin', { 
+      admin_action: 'insert_document',
+      database: this.database_name,
+      collection: collection_name,
+      document
+    });
+  }
+  
+  /**
+   * Updates a document in a collection (admin operation).
+   * @param {string} collection_name - Name of collection
+   * @param {string} document_id - Document ID
+   * @param {Object} update - Update operations
+   * @returns {Promise<Object>} Update document result
+   */
+  async update_document(collection_name, document_id, update) {
+    return this.client.send_request('admin', { 
+      admin_action: 'update_document',
+      database: this.database_name,
+      collection: collection_name,
+      document_id,
+      update
+    });
+  }
+  
+  /**
+   * Deletes a document from a collection (admin operation).
+   * @param {string} collection_name - Name of collection
+   * @param {string} document_id - Document ID
+   * @returns {Promise<Object>} Delete document result
+   */
+  async delete_document(collection_name, document_id) {
+    return this.client.send_request('admin', { 
+      admin_action: 'delete_document',
+      database: this.database_name,
+      collection: collection_name,
+      document_id
+    });
+  }
+}
+
+export default Database;