s3db.js 12.1.0 → 12.2.1

package/src/cli/migration-manager.js

@@ -0,0 +1,270 @@
+/**
+ * Migration Manager for s3db.js
+ * Handles database schema migrations
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+export class MigrationManager {
+  constructor(database, migrationsDir = './migrations') {
+    this.database = database;
+    this.migrationsDir = migrationsDir;
+    this.migrationResource = null;
+  }
+
+  /**
+   * Initialize migrations system
+   */
+  async init() {
+    // Create migrations resource if it doesn't exist
+    const resources = await this.database.listResources();
+    const exists = resources.find(r => r.name === '_migrations');
+
+    if (!exists) {
+      this.migrationResource = await this.database.createResource({
+        name: '_migrations',
+        attributes: {
+          id: 'string|required',
+          name: 'string|required',
+          batch: 'number|default:1',
+          executedAt: 'string'
+        },
+        timestamps: true,
+        behavior: 'enforce-limits'
+      });
+    } else {
+      this.migrationResource = await this.database.resource('_migrations');
+    }
+
+    // Ensure migrations directory exists
+    try {
+      await fs.mkdir(this.migrationsDir, { recursive: true });
+    } catch (err) {
+      // Directory exists
+    }
+  }
+
+  /**
+   * Generate a new migration file
+   */
+  async generate(name) {
+    const timestamp = new Date().toISOString().replace(/[-:]/g, '').split('.')[0];
+    const filename = `${timestamp}_${name}.js`;
+    const filepath = path.join(this.migrationsDir, filename);
+
+    const template = `/**
+ * Migration: ${name}
+ * Generated: ${new Date().toISOString()}
+ */
+
+export async function up(database) {
+  // Add migration logic here
+  // Example:
+  // await database.createResource({
+  //   name: 'users',
+  //   attributes: {
+  //     id: 'string|required',
+  //     email: 'string|required|email',
+  //     name: 'string|required'
+  //   },
+  //   timestamps: true
+  // });
+}
+
+export async function down(database) {
+  // Add rollback logic here
+  // Example:
+  // await database.deleteResource('users');
+}
+`;
+
+    await fs.writeFile(filepath, template);
+    return { filename, filepath };
+  }
+
+  /**
+   * Get all migration files
+   */
+  async getMigrationFiles() {
+    try {
+      const files = await fs.readdir(this.migrationsDir);
+      return files
+        .filter(f => f.endsWith('.js'))
+        .sort();
+    } catch (err) {
+      return [];
+    }
+  }
+
+  /**
+   * Get executed migrations from database
+   */
+  async getExecutedMigrations() {
+    try {
+      const migrations = await this.migrationResource.list();
+      return migrations.map(m => m.name);
+    } catch (err) {
+      return [];
+    }
+  }
+
+  /**
+   * Get current batch number
+   */
+  async getCurrentBatch() {
+    try {
+      const migrations = await this.migrationResource.list();
+      if (migrations.length === 0) return 0;
+
+      const batches = migrations.map(m => m.batch || 0);
+      return Math.max(...batches);
+    } catch (err) {
+      return 0;
+    }
+  }
+
+  /**
+   * Get pending migrations
+   */
+  async getPendingMigrations() {
+    const allFiles = await this.getMigrationFiles();
+    const executed = await this.getExecutedMigrations();
+
+    return allFiles.filter(f => !executed.includes(f));
+  }
+
+  /**
+   * Run pending migrations
+   */
+  async up(options = {}) {
+    const { step = null } = options;
+    const pending = await this.getPendingMigrations();
+
+    if (pending.length === 0) {
+      return { message: 'No pending migrations', migrations: [] };
+    }
+
+    const toRun = step ? pending.slice(0, step) : pending;
+    const batch = (await this.getCurrentBatch()) + 1;
+    const executed = [];
+
+    for (const filename of toRun) {
+      const filepath = path.join(process.cwd(), this.migrationsDir, filename);
+      const migration = await import(filepath);
+
+      // Execute up
+      await migration.up(this.database);
+
+      // Record migration
+      await this.migrationResource.insert({
+        id: filename,
+        name: filename,
+        batch,
+        executedAt: new Date().toISOString()
+      });
+
+      executed.push(filename);
+    }
+
+    return { message: `Executed ${executed.length} migrations`, migrations: executed, batch };
+  }
+
+  /**
+   * Rollback migrations
+   */
+  async down(options = {}) {
+    const { step = 1 } = options;
+
+    const allMigrations = await this.migrationResource.list();
+    if (allMigrations.length === 0) {
+      return { message: 'No migrations to rollback', migrations: [] };
+    }
+
+    // Sort by batch descending, then by name descending
+    allMigrations.sort((a, b) => {
+      if (a.batch !== b.batch) return b.batch - a.batch;
+      return b.name.localeCompare(a.name);
+    });
+
+    const currentBatch = allMigrations[0].batch;
+    const toRollback = allMigrations
+      .filter(m => m.batch === currentBatch)
+      .slice(0, step);
+
+    const rolledBack = [];
+
+    for (const migration of toRollback) {
+      const filepath = path.join(process.cwd(), this.migrationsDir, migration.name);
+      const migrationModule = await import(filepath);
+
+      // Execute down
+      await migrationModule.down(this.database);
+
+      // Remove migration record
+      await this.migrationResource.delete(migration.id);
+
+      rolledBack.push(migration.name);
+    }
+
+    return { message: `Rolled back ${rolledBack.length} migrations`, migrations: rolledBack };
+  }
+
+  /**
+   * Reset all migrations
+   */
+  async reset() {
+    const allMigrations = await this.migrationResource.list();
+
+    // Sort in reverse order for rollback
+    allMigrations.sort((a, b) => {
+      if (a.batch !== b.batch) return b.batch - a.batch;
+      return b.name.localeCompare(a.name);
+    });
+
+    const rolledBack = [];
+
+    for (const migration of allMigrations) {
+      const filepath = path.join(process.cwd(), this.migrationsDir, migration.name);
+      const migrationModule = await import(filepath);
+
+      // Execute down
+      await migrationModule.down(this.database);
+
+      // Remove migration record
+      await this.migrationResource.delete(migration.id);
+
+      rolledBack.push(migration.name);
+    }
+
+    return { message: `Reset ${rolledBack.length} migrations`, migrations: rolledBack };
+  }
+
+  /**
+   * Get migration status
+   */
+  async status() {
+    const allFiles = await this.getMigrationFiles();
+    const executed = await this.getExecutedMigrations();
+    const executedRecords = await this.migrationResource.list();
+
+    const executedMap = {};
+    executedRecords.forEach(m => {
+      executedMap[m.name] = m;
+    });
+
+    return allFiles.map(filename => {
+      const isExecuted = executed.includes(filename);
+      const record = executedMap[filename];
+
+      return {
+        name: filename,
+        status: isExecuted ? 'executed' : 'pending',
+        batch: record?.batch || null,
+        executedAt: record?.executedAt || null
+      };
+    });
+  }
+}
+
+export default MigrationManager;

package/src/concerns/calculator.js

@@ -66,10 +66,6 @@ export function clearUTF8Memory() {
   utf8BytesMemory.clear();
 }
 
-// Aliases for backward compatibility
-export const clearUTF8Memo = clearUTF8Memory;
-export const clearUTF8Cache = clearUTF8Memory;
-
 /**
  * Calculates the size in bytes of attribute names (mapped to digits)
  * @param {Object} mappedObject - The object returned by schema.mapper()

package/src/concerns/metadata-encoding.js

@@ -464,24 +464,7 @@ export function metadataDecode(value) {
     }
   }
 
-  // No prefix - return as is (backwards compatibility)
-  // Try to detect if it's base64 without prefix (legacy)
-  // OPTIMIZATION: Quick reject before expensive regex
-  const len = value.length;
-  if (len > 0 && len % 4 === 0) { // Base64 is always multiple of 4
-    if (/^[A-Za-z0-9+/]+=*$/.test(value)) {
-      try {
-        const decoded = Buffer.from(value, 'base64').toString('utf8');
-        // Verify it's valid UTF-8 with special chars
-        if (/[^\x00-\x7F]/.test(decoded) && Buffer.from(decoded, 'utf8').toString('base64') === value) {
-          return decoded;
-        }
-      } catch {
-        // Not base64, return as is
-      }
-    }
-  }
-
+  // No prefix - return as is
   return value;
 }
 
@@ -490,9 +473,6 @@ export function metadataDecode(value) {
  * @param {string} value - Value to calculate size for
  * @returns {Object} Size information
  */
-// Backwards compatibility exports
-export { metadataEncode as smartEncode, metadataDecode as smartDecode };
-
 export function calculateEncodedSize(value) {
   const analysis = analyzeString(value);
   const originalSize = Buffer.byteLength(value, 'utf8');

package/src/concerns/plugin-storage.js

@@ -134,11 +134,24 @@ export class PluginStorage {
   }
 
   /**
-   * Alias for set() to maintain backward compatibility
-   * @deprecated Use set() instead
+   * Batch set multiple items
+   *
+   * @param {Array<{key: string, data: Object, options?: Object}>} items - Items to save
+   * @returns {Promise<Array<{ok: boolean, key: string, error?: Error}>>} Results
    */
-  async put(key, data, options = {}) {
-    return this.set(key, data, options);
+  async batchSet(items) {
+    const results = [];
+
+    for (const item of items) {
+      try {
+        await this.set(item.key, item.data, item.options || {});
+        results.push({ ok: true, key: item.key });
+      } catch (error) {
+        results.push({ ok: false, key: item.key, error });
+      }
+    }
+
+    return results;
   }
 
   /**

package/src/concerns/typescript-generator.d.ts

@@ -0,0 +1,171 @@
+/**
+ * TypeScript Definition Generator for s3db.js
+ *
+ * Automatically generates type-safe interfaces from your s3db.js resources.
+ *
+ * @module s3db.js/typescript-generator
+ * @example
+ * ```typescript
+ * import { Database } from 's3db.js';
+ * import { generateTypes } from 's3db.js/typescript-generator';
+ *
+ * const db = new Database({ connectionString: '...' });
+ *
+ * await db.createResource({
+ *   name: 'users',
+ *   attributes: {
+ *     name: 'string|required',
+ *     email: 'string|required|email',
+ *     age: 'number'
+ *   }
+ * });
+ *
+ * // Generate TypeScript definitions
+ * await generateTypes(db, { outputPath: './types/database.d.ts' });
+ *
+ * // Now you get full autocomplete!
+ * import { Users } from './types/database';
+ * const user: Users = await db.resources.users.get('id');
+ * ```
+ */
+
+import type { Database } from 's3db.js';
+
+/**
+ * Options for generating TypeScript definitions
+ */
+export interface GenerateTypesOptions {
+  /**
+   * Output path for the generated .d.ts file
+   * @example './types/database.d.ts'
+   */
+  outputPath: string;
+
+  /**
+   * Module name to augment with resource types
+   * @default 's3db.js'
+   */
+  moduleName?: string;
+
+  /**
+   * Include JSDoc comments in generated types
+   * @default true
+   */
+  includeComments?: boolean;
+
+  /**
+   * Custom header comment to add to generated file
+   * @example 'Auto-generated types for MyApp database'
+   */
+  header?: string;
+
+  /**
+   * Include resource metadata in generated types
+   * @default false
+   */
+  includeMetadata?: boolean;
+
+  /**
+   * Format style for generated code
+   * @default 'prettier'
+   */
+  formatStyle?: 'prettier' | 'compact' | 'none';
+}
+
+/**
+ * Result of type generation
+ */
+export interface GenerateTypesResult {
+  /**
+   * Number of resource interfaces generated
+   */
+  resourceCount: number;
+
+  /**
+   * List of generated resource names
+   */
+  resources: string[];
+
+  /**
+   * Output file path
+   */
+  outputPath: string;
+
+  /**
+   * Generated content (before writing to file)
+   */
+  content: string;
+}
+
+/**
+ * Generate TypeScript definitions from database resources
+ *
+ * Creates a .d.ts file with type-safe interfaces for all resources in the database.
+ * The generated file includes:
+ * - Interface for each resource with all fields typed
+ * - ResourceMap interface for type-safe db.resources access
+ * - Module augmentation for s3db.js Database class
+ *
+ * @param database - s3db.js Database instance with resources
+ * @param options - Generation options
+ * @returns Promise<void>
+ *
+ * @throws {Error} If database has no resources
+ * @throws {Error} If output directory doesn't exist
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * await generateTypes(db, { outputPath: './types/db.d.ts' });
+ *
+ * // With custom options
+ * await generateTypes(db, {
+ *   outputPath: './types/db.d.ts',
+ *   moduleName: 's3db.js',
+ *   includeComments: true,
+ *   header: 'Generated types for MyApp'
+ * });
+ * ```
+ */
+export function generateTypes(
+  database: Database,
+  options: GenerateTypesOptions
+): Promise<void>;
+
+/**
+ * Map s3db.js field types to TypeScript types
+ *
+ * @param fieldType - s3db.js field type string (e.g., 'string|required', 'number', 'embedding:1536')
+ * @returns TypeScript type string
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * mapFieldTypeToTypeScript('string|required') // 'string'
+ * mapFieldTypeToTypeScript('number') // 'number'
+ * mapFieldTypeToTypeScript('embedding:1536') // 'number[] /* 1536 dimensions *\/'
+ * ```
+ */
+export function mapFieldTypeToTypeScript(fieldType: string): string;
+
+/**
+ * Check if a field is optional based on its validation rules
+ *
+ * @param fieldType - s3db.js field type string
+ * @returns True if field is optional (no 'required' rule)
+ *
+ * @internal
+ */
+export function isFieldOptional(fieldType: string): boolean;
+
+/**
+ * Generate JSDoc comment for a field
+ *
+ * @param fieldName - Name of the field
+ * @param fieldType - s3db.js field type string
+ * @returns JSDoc comment string
+ *
+ * @internal
+ */
+export function generateFieldComment(fieldName: string, fieldType: string): string;