s3db.js 12.0.1 → 12.2.0

package/src/concerns/typescript-generator.js

@@ -0,0 +1,275 @@
+/**
+ * TypeScript Definition Generator
+ *
+ * Generates .d.ts files from s3db.js resource schemas for type safety and autocomplete.
+ *
+ * Usage:
+ *   import { generateTypes } from 's3db.js/typescript-generator';
+ *   await generateTypes(database, { outputPath: './types/database.d.ts' });
+ *
+ * Features:
+ * - Auto-generates TypeScript interfaces from resource schemas
+ * - Type-safe property access (db.resources.users)
+ * - Autocomplete for resource methods
+ * - Detects typos at compile time (user.emai → error!)
+ */
+
+import { writeFile, mkdir } from 'fs/promises';
+import { dirname } from 'path';
+
+/**
+ * Map s3db.js field types to TypeScript types
+ * @param {string} fieldType - s3db.js field type
+ * @returns {string} TypeScript type
+ */
+function mapFieldTypeToTypeScript(fieldType) {
+  // Extract base type from validation rules (e.g., "string|required" → "string")
+  const baseType = fieldType.split('|')[0].trim();
+
+  const typeMap = {
+    'string': 'string',
+    'number': 'number',
+    'integer': 'number',
+    'boolean': 'boolean',
+    'array': 'any[]',
+    'object': 'Record<string, any>',
+    'json': 'Record<string, any>',
+    'secret': 'string',
+    'email': 'string',
+    'url': 'string',
+    'date': 'string', // ISO date string
+    'datetime': 'string', // ISO datetime string
+    'ip4': 'string',
+    'ip6': 'string',
+  };
+
+  // Handle embedding:N notation
+  if (baseType.startsWith('embedding:')) {
+    const dimensions = parseInt(baseType.split(':')[1]);
+    return `number[] /* ${dimensions} dimensions */`;
+  }
+
+  return typeMap[baseType] || 'any';
+}
+
+/**
+ * Check if field is required based on validation rules
+ * @param {string} fieldDef - Field definition
+ * @returns {boolean} True if required
+ */
+function isFieldRequired(fieldDef) {
+  if (typeof fieldDef === 'string') {
+    return fieldDef.includes('|required');
+  }
+  if (typeof fieldDef === 'object' && fieldDef.required) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Generate TypeScript interface for a resource
+ * @param {string} resourceName - Resource name
+ * @param {Object} attributes - Resource attributes
+ * @param {boolean} timestamps - Whether timestamps are enabled
+ * @returns {string} TypeScript interface definition
+ */
+function generateResourceInterface(resourceName, attributes, timestamps = false) {
+  const interfaceName = toPascalCase(resourceName);
+  const lines = [];
+
+  lines.push(`export interface ${interfaceName} {`);
+
+  // Add id field (always present)
+  lines.push(`  /** Resource ID (auto-generated) */`);
+  lines.push(`  id: string;`);
+  lines.push('');
+
+  // Add user-defined attributes
+  for (const [fieldName, fieldDef] of Object.entries(attributes)) {
+    const required = isFieldRequired(fieldDef);
+    const optional = required ? '' : '?';
+
+    // Extract type
+    let tsType;
+    if (typeof fieldDef === 'string') {
+      tsType = mapFieldTypeToTypeScript(fieldDef);
+    } else if (typeof fieldDef === 'object' && fieldDef.type) {
+      tsType = mapFieldTypeToTypeScript(fieldDef.type);
+
+      // Handle nested objects
+      if (fieldDef.type === 'object' && fieldDef.props) {
+        tsType = '{\n';
+        for (const [propName, propDef] of Object.entries(fieldDef.props)) {
+          const propType = typeof propDef === 'string'
+            ? mapFieldTypeToTypeScript(propDef)
+            : mapFieldTypeToTypeScript(propDef.type);
+          const propRequired = isFieldRequired(propDef);
+          tsType += `    ${propName}${propRequired ? '' : '?'}: ${propType};\n`;
+        }
+        tsType += '  }';
+      }
+
+      // Handle arrays with typed items
+      if (fieldDef.type === 'array' && fieldDef.items) {
+        const itemType = mapFieldTypeToTypeScript(fieldDef.items);
+        tsType = `Array<${itemType}>`;
+      }
+    } else {
+      tsType = 'any';
+    }
+
+    // Add JSDoc comment if description exists
+    if (fieldDef.description) {
+      lines.push(`  /** ${fieldDef.description} */`);
+    }
+
+    lines.push(`  ${fieldName}${optional}: ${tsType};`);
+  }
+
+  // Add timestamp fields if enabled
+  if (timestamps) {
+    lines.push('');
+    lines.push(`  /** Creation timestamp (ISO 8601) */`);
+    lines.push(`  createdAt: string;`);
+    lines.push(`  /** Last update timestamp (ISO 8601) */`);
+    lines.push(`  updatedAt: string;`);
+  }
+
+  lines.push('}');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Convert string to PascalCase
+ * @param {string} str - String to convert
+ * @returns {string} PascalCase string
+ */
+function toPascalCase(str) {
+  return str
+    .split(/[_-]/)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+/**
+ * Generate TypeScript definitions for all resources
+ * @param {Database} database - s3db.js Database instance
+ * @param {Object} options - Generation options
+ * @param {string} options.outputPath - Output file path (default: ./types/database.d.ts)
+ * @param {string} options.moduleName - Module name for import (default: s3db.js)
+ * @param {boolean} options.includeResource - Include Resource class methods (default: true)
+ * @returns {Promise<string>} Generated TypeScript definitions
+ */
+export async function generateTypes(database, options = {}) {
+  const {
+    outputPath = './types/database.d.ts',
+    moduleName = 's3db.js',
+    includeResource = true
+  } = options;
+
+  const lines = [];
+
+  // File header
+  lines.push('/**');
+  lines.push(' * Auto-generated TypeScript definitions for s3db.js resources');
+  lines.push(' * Generated at: ' + new Date().toISOString());
+  lines.push(' * DO NOT EDIT - This file is auto-generated');
+  lines.push(' */');
+  lines.push('');
+
+  // Import base types from s3db.js
+  if (includeResource) {
+    lines.push(`import { Resource, Database } from '${moduleName}';`);
+    lines.push('');
+  }
+
+  // Generate interfaces for each resource
+  const resourceInterfaces = [];
+
+  for (const [name, resource] of Object.entries(database.resources)) {
+    const attributes = resource.config?.attributes || resource.attributes || {};
+    const timestamps = resource.config?.timestamps || false;
+
+    const interfaceDef = generateResourceInterface(name, attributes, timestamps);
+    lines.push(interfaceDef);
+
+    resourceInterfaces.push({
+      name,
+      interfaceName: toPascalCase(name),
+      resource
+    });
+  }
+
+  // Generate ResourceMap interface for db.resources
+  lines.push('/**');
+  lines.push(' * Typed resource map for property access');
+  lines.push(' * @example');
+  lines.push(' * const users = db.resources.users; // Type-safe!');
+  lines.push(' * const user = await users.get("id"); // Autocomplete works!');
+  lines.push(' */');
+  lines.push('export interface ResourceMap {');
+
+  for (const { name, interfaceName } of resourceInterfaces) {
+    lines.push(`  /** ${interfaceName} resource */`);
+    if (includeResource) {
+      lines.push(`  ${name}: Resource<${interfaceName}>;`);
+    } else {
+      lines.push(`  ${name}: any;`);
+    }
+  }
+
+  lines.push('}');
+  lines.push('');
+
+  // Generate Database extension with typed resources property
+  if (includeResource) {
+    lines.push('/**');
+    lines.push(' * Extended Database class with typed resources');
+    lines.push(' */');
+    lines.push('declare module \'s3db.js\' {');
+    lines.push('  interface Database {');
+    lines.push('    resources: ResourceMap;');
+    lines.push('  }');
+    lines.push('');
+    lines.push('  interface Resource<T = any> {');
+    lines.push('    get(id: string): Promise<T>;');
+    lines.push('    getOrNull(id: string): Promise<T | null>;');
+    lines.push('    getOrThrow(id: string): Promise<T>;');
+    lines.push('    insert(data: Partial<T>): Promise<T>;');
+    lines.push('    update(id: string, data: Partial<T>): Promise<T>;');
+    lines.push('    patch(id: string, data: Partial<T>): Promise<T>;');
+    lines.push('    replace(id: string, data: Partial<T>): Promise<T>;');
+    lines.push('    delete(id: string): Promise<void>;');
+    lines.push('    list(options?: any): Promise<T[]>;');
+    lines.push('    query(filters: Partial<T>, options?: any): Promise<T[]>;');
+    lines.push('    validate(data: Partial<T>, options?: any): Promise<{ valid: boolean; errors: any[]; data: T | null }>;');
+    lines.push('  }');
+    lines.push('}');
+  }
+
+  const content = lines.join('\n');
+
+  // Write to file if outputPath provided
+  if (outputPath) {
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, content, 'utf-8');
+  }
+
+  return content;
+}
+
+/**
+ * Generate types and log to console
+ * @param {Database} database - s3db.js Database instance
+ * @param {Object} options - Generation options
+ */
+export async function printTypes(database, options = {}) {
+  const types = await generateTypes(database, { ...options, outputPath: null });
+  console.log(types);
+  return types;
+}
+
+export default { generateTypes, printTypes };

package/src/database.class.js

@@ -18,19 +18,47 @@ export class Database extends EventEmitter {
     this.version = "1";
     // Version is injected during build, fallback to "latest" for development
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => (typeof __PACKAGE_VERSION__ !== 'undefined' && __PACKAGE_VERSION__ !== '__PACKAGE_VERSION__' 
-        ? __PACKAGE_VERSION__ 
+      const [ok, err, version] = tryFn(() => (typeof __PACKAGE_VERSION__ !== 'undefined' && __PACKAGE_VERSION__ !== '__PACKAGE_VERSION__'
+        ? __PACKAGE_VERSION__
         : "latest"));
       return ok ? version : "latest";
     })();
-    this.resources = {};
+
+    // Create Proxy for resources to enable property access (db.resources.users)
+    this._resourcesMap = {};
+    this.resources = new Proxy(this._resourcesMap, {
+      get: (target, prop) => {
+        // Allow standard Object methods
+        if (typeof prop === 'symbol' || prop === 'constructor' || prop === 'toJSON') {
+          return target[prop];
+        }
+
+        // Return resource if exists
+        if (target[prop]) {
+          return target[prop];
+        }
+
+        // Return undefined for non-existent resources (enables optional chaining)
+        return undefined;
+      },
+
+      // Support Object.keys(), Object.entries(), etc.
+      ownKeys: (target) => {
+        return Object.keys(target);
+      },
+
+      getOwnPropertyDescriptor: (target, prop) => {
+        return Object.getOwnPropertyDescriptor(target, prop);
+      }
+    });
+
     this.savedMetadata = null; // Store loaded metadata for versioning
     this.options = options;
     this.verbose = options.verbose || false;
     this.parallelism = parseInt(options.parallelism + "") || 10;
-    this.plugins = options.plugins || []; // Keep the original array for backward compatibility
-    this.pluginRegistry = {}; // Initialize plugins registry as separate object
-    this.pluginList = options.plugins || []; // Keep the list for backward compatibility
+    this.pluginList = options.plugins || [];
+    this.pluginRegistry = {};
+    this.plugins = this.pluginRegistry; // Alias for plugin registry
     this.cache = options.cache;
     this.passphrase = options.passphrase || "secret";
     this.versioningEnabled = options.versioningEnabled || false;
@@ -181,7 +209,7 @@ export class Database extends EventEmitter {
           restoredIdSize = versionData.idSize || 22;
         }
 
-        this.resources[name] = new Resource({
+        this._resourcesMap[name] = new Resource({
           name,
           client: this.client,
           database: this, // ensure reference
@@ -259,7 +287,7 @@ export class Database extends EventEmitter {
     
     // Check for deleted resources
     for (const [name, savedResource] of Object.entries(savedMetadata.resources || {})) {
-      if (!this.resources[name]) {
+      if (!this._resourcesMap[name]) {
         const currentVersion = savedResource.currentVersion || 'v1';
         const versionData = savedResource.versions?.[currentVersion];
         changes.push({
@@ -894,7 +922,7 @@ export class Database extends EventEmitter {
    * @returns {boolean} True if resource exists, false otherwise
    */
   resourceExists(name) {
-    return !!this.resources[name];
+    return !!this._resourcesMap[name];
   }
 
   /**
@@ -903,17 +931,16 @@ export class Database extends EventEmitter {
    * @param {string} config.name - Resource name
    * @param {Object} config.attributes - Resource attributes
    * @param {string} [config.behavior] - Resource behavior
-   * @param {Object} [config.options] - Resource options (deprecated, use root level parameters)
    * @returns {Object} Result with exists and hash information
    */
-  resourceExistsWithSameHash({ name, attributes, behavior = 'user-managed', partitions = {}, options = {} }) {
-    if (!this.resources[name]) {
+  resourceExistsWithSameHash({ name, attributes, behavior = 'user-managed', partitions = {} }) {
+    if (!this._resourcesMap[name]) {
       return { exists: false, sameHash: false, hash: null };
     }
 
-    const existingResource = this.resources[name];
+    const existingResource = this._resourcesMap[name];
     const existingHash = this.generateDefinitionHash(existingResource.export());
-    
+
     // Create a mock resource to calculate the new hash
     const mockResource = new Resource({
       name,
@@ -923,8 +950,7 @@ export class Database extends EventEmitter {
       client: this.client,
       version: existingResource.version,
       passphrase: this.passphrase,
-      versioningEnabled: this.versioningEnabled,
-      ...options
+      versioningEnabled: this.versioningEnabled
     });
     
     const newHash = this.generateDefinitionHash(mockResource.export());
@@ -955,13 +981,67 @@ export class Database extends EventEmitter {
    * @param {string} [config.createdBy='user'] - Who created this resource ('user', 'plugin', or plugin name)
    * @returns {Promise<Resource>} The created or updated resource
    */
-  async createResource({ name, attributes, behavior = 'user-managed', hooks, ...config }) {
-    if (this.resources[name]) {
-      const existingResource = this.resources[name];
+  /**
+   * Normalize partitions config from array or object format
+   * @param {Array|Object} partitions - Partitions config
+   * @param {Object} attributes - Resource attributes
+   * @returns {Object} Normalized partitions object
+   * @private
+   */
+  _normalizePartitions(partitions, attributes) {
+    // If already an object, return as-is
+    if (!Array.isArray(partitions)) {
+      return partitions || {};
+    }
+
+    // Transform array into object with auto-generated names
+    const normalized = {};
+
+    for (const fieldName of partitions) {
+      if (typeof fieldName !== 'string') {
+        throw new Error(`Partition field must be a string, got ${typeof fieldName}`);
+      }
+
+      if (!attributes[fieldName]) {
+        throw new Error(`Partition field '${fieldName}' not found in attributes`);
+      }
+
+      // Generate partition name: byFieldName (capitalize first letter)
+      const partitionName = `by${fieldName.charAt(0).toUpperCase()}${fieldName.slice(1)}`;
+
+      // Extract field type from attributes
+      const fieldDef = attributes[fieldName];
+      let fieldType = 'string'; // default
+
+      if (typeof fieldDef === 'string') {
+        // String format: "string|required" -> extract "string"
+        fieldType = fieldDef.split('|')[0].trim();
+      } else if (typeof fieldDef === 'object' && fieldDef.type) {
+        // Object format: { type: 'string', required: true }
+        fieldType = fieldDef.type;
+      }
+
+      normalized[partitionName] = {
+        fields: {
+          [fieldName]: fieldType
+        }
+      };
+    }
+
+    return normalized;
+  }
+
+  async createResource({ name, attributes, behavior = 'user-managed', hooks, middlewares, ...config }) {
+    // Normalize partitions (support array shorthand)
+    const normalizedPartitions = this._normalizePartitions(config.partitions, attributes);
+
+    if (this._resourcesMap[name]) {
+      const existingResource = this._resourcesMap[name];
       // Update configuration
       Object.assign(existingResource.config, {
         cache: this.cache,
         ...config,
+        partitions: normalizedPartitions
       });
       if (behavior) {
         existingResource.behavior = behavior;
@@ -981,6 +1061,11 @@ export class Database extends EventEmitter {
           }
         }
       }
+      // Apply middlewares if provided
+      if (middlewares) {
+        this._applyMiddlewares(existingResource, middlewares);
+      }
+
       // Only upload metadata if hash actually changed
       const newHash = this.generateDefinitionHash(existingResource.export(), existingResource.behavior);
       const existingMetadata = this.savedMetadata?.resources?.[name];
@@ -1005,7 +1090,7 @@ export class Database extends EventEmitter {
       observers: [this],
       cache: config.cache !== undefined ? config.cache : this.cache,
       timestamps: config.timestamps !== undefined ? config.timestamps : false,
-      partitions: config.partitions || {},
+      partitions: normalizedPartitions,
       paranoid: config.paranoid !== undefined ? config.paranoid : true,
       allNestedObjectsOptional: config.allNestedObjectsOptional !== undefined ? config.allNestedObjectsOptional : true,
       autoDecrypt: config.autoDecrypt !== undefined ? config.autoDecrypt : true,
@@ -1021,18 +1106,76 @@ export class Database extends EventEmitter {
       createdBy: config.createdBy || 'user'
     });
     resource.database = this;
-    this.resources[name] = resource;
+    this._resourcesMap[name] = resource;
+
+    // Apply middlewares if provided
+    if (middlewares) {
+      this._applyMiddlewares(resource, middlewares);
+    }
+
     await this.uploadMetadataFile();
     this.emit("s3db.resourceCreated", name);
     return resource;
   }
 
-  resource(name) {
-    if (!this.resources[name]) {
-      return Promise.reject(`resource ${name} does not exist`);
+  /**
+   * Apply middlewares to a resource
+   * @param {Resource} resource - Resource instance
+   * @param {Array|Object} middlewares - Middlewares config
+   * @private
+   */
+  _applyMiddlewares(resource, middlewares) {
+    // Format 1: Array of functions (applies to all methods)
+    if (Array.isArray(middlewares)) {
+      // Apply to all middleware-supported methods
+      const methods = resource._middlewareMethods || [
+        'get', 'list', 'listIds', 'getAll', 'count', 'page',
+        'insert', 'update', 'delete', 'deleteMany', 'exists', 'getMany',
+        'content', 'hasContent', 'query', 'getFromPartition', 'setContent',
+        'deleteContent', 'replace', 'patch'
+      ];
+
+      for (const method of methods) {
+        for (const middleware of middlewares) {
+          if (typeof middleware === 'function') {
+            resource.useMiddleware(method, middleware);
+          }
+        }
+      }
+      return;
     }
 
-    return this.resources[name];
+    // Format 2: Object with method-specific middlewares
+    if (typeof middlewares === 'object' && middlewares !== null) {
+      for (const [method, fns] of Object.entries(middlewares)) {
+        if (method === '*') {
+          // Apply to all methods
+          const methods = resource._middlewareMethods || [
+            'get', 'list', 'listIds', 'getAll', 'count', 'page',
+            'insert', 'update', 'delete', 'deleteMany', 'exists', 'getMany',
+            'content', 'hasContent', 'query', 'getFromPartition', 'setContent',
+            'deleteContent', 'replace', 'patch'
+          ];
+
+          const middlewareArray = Array.isArray(fns) ? fns : [fns];
+          for (const targetMethod of methods) {
+            for (const middleware of middlewareArray) {
+              if (typeof middleware === 'function') {
+                resource.useMiddleware(targetMethod, middleware);
+              }
+            }
+          }
+        } else {
+          // Apply to specific method
+          const middlewareArray = Array.isArray(fns) ? fns : [fns];
+          for (const middleware of middlewareArray) {
+            if (typeof middleware === 'function') {
+              resource.useMiddleware(method, middleware);
+            }
+          }
+        }
+      }
+    }
   }
 
   /**
@@ -1049,14 +1192,14 @@ export class Database extends EventEmitter {
    * @returns {Resource} Resource instance
    */
   async getResource(name) {
-    if (!this.resources[name]) {
+    if (!this._resourcesMap[name]) {
       throw new ResourceNotFound({
         bucket: this.client.config.bucket,
         resourceName: name,
         id: name
       });
     }
-    return this.resources[name];
+    return this._resourcesMap[name];
   }
 
   /**
@@ -1120,7 +1263,7 @@ export class Database extends EventEmitter {
           });
         }
         // Instead of reassigning, clear in place
-        Object.keys(this.resources).forEach(k => delete this.resources[k]);
+        Object.keys(this.resources).forEach(k => delete this._resourcesMap[k]);
       }
 
       // 3. Remove all listeners from the client

package/src/index.js

@@ -13,20 +13,26 @@ export { Validator } from './validator.class.js'
 export { ConnectionString } from './connection-string.class.js'
 
 // stream classes
-export { 
-  ResourceReader, 
-  ResourceWriter, 
-  ResourceIdsReader, 
+export {
+  ResourceReader,
+  ResourceWriter,
+  ResourceIdsReader,
   ResourceIdsPageReader,
   streamToString
 } from './stream/index.js'
 
+// typescript generation
+export { generateTypes, printTypes } from './concerns/typescript-generator.js'
+
+// testing utilities
+export { Factory, Seeder } from './testing/index.js'
+
 // behaviors
-export { 
-  behaviors, 
-  getBehavior, 
-  AVAILABLE_BEHAVIORS, 
-  DEFAULT_BEHAVIOR 
+export {
+  behaviors,
+  getBehavior,
+  AVAILABLE_BEHAVIORS,
+  DEFAULT_BEHAVIOR
 } from './behaviors/index.js'
 
 // default

package/src/plugins/api/index.js

@@ -56,7 +56,6 @@ export class ApiPlugin extends Plugin {
       host: options.host || '0.0.0.0',
       verbose: options.verbose || false,
 
-      // API Documentation (supports both new and legacy formats)
       docs: {
         enabled: options.docs?.enabled !== false && options.docsEnabled !== false, // Enable by default
         ui: options.docs?.ui || 'redoc', // 'swagger' or 'redoc' (redoc is prettier!)