@questwork/q-utilities 0.1.30 → 0.1.32

package/BEST_PRACTICES.md

@@ -0,0 +1,217 @@
+# Best Practices for Questwork Model Projects
+
+This document outlines the best practices for developing and maintaining Questwork model projects. It is intended to guide both AI agents and developers on key principles and considerations.
+
+## 1. Code Structure
+
+### 1.1 File Organization
+- **Models**: Place all data models in `lib/models/` directory
+- **Constants**: Place all constant definitions in `lib/constants/` directory
+- **Helpers**: Place utility functions in `lib/helpers/` directory
+- **Tests**: Place unit tests next to the corresponding model files with `.spec.ts` extension
+
+### 1.2 Export Patterns
+- Place all exports at the bottom of the file
+- Separate named exports from type exports
+- Use clear, consistent export patterns
+
+Example:
+```typescript
+export {
+  BaseModel
+}
+
+export type {
+  BaseModelOptions, BaseModelUpdate
+}
+```
+
+## 2. TypeScript Best Practices
+
+### 2.1 Type Definitions
+- Use interfaces for complex type definitions
+- Use `as const` for constant objects to create literal types
+- Define types for all function parameters and return values
+
+### 2.2 Coding Style
+- **Semi-colons**: Do not use semi-colons at the end of lines
+- **Naming Conventions**:
+  - Constants: `CONSTANT_CASE`
+  - Interfaces: `PascalCase`
+  - Classes: `PascalCase`
+  - Methods and functions: `camelCase`
+  - Properties: `camelCase`
+  - Private properties: `_underscorePrefix`
+- **Ordering**:
+  - Place `[key: string]: any` at the top of class definitions
+  - Order class properties in alphabetical order
+  - Order class methods in alphabetical order
+
+### 2.3 Model Patterns
+- Extend appropriate base classes for shared functionality
+- Use `init()` method for object creation
+- Include static methods for testing purposes
+- Define arrays to restrict updatable fields
+- **Unique Identifiers**:
+  - Use `xxxCode` as the primary unique ID
+  - Generate unique codes using appropriate utility functions
+  - Maintain compatibility with different ID formats
+
+## 3. Business Logic
+
+### 3.1 Data Integrity
+- **Immutable Fields**: Once created, most fields should not be updatable
+- **Unique Identifiers**: Use consistent patterns for generating unique codes
+- **Timestamps**: Use `Date.now()` for timestamps
+
+### 3.2 Separation of Concerns
+- **Data Models**: Should only contain data structure and basic validation
+- **Repository Logic**: Should be implemented in the application layer
+- **Business Logic**: Should be implemented in the application layer
+
+## 4. Testing
+
+### 4.1 Test Patterns
+- Use Vitest for unit testing
+- Place test files next to the corresponding model files
+- Use descriptive test names
+- Set test values to match field names (e.g., `myCode: 'myCode'`)
+- Test both success and failure cases
+
+### 4.2 Test Coverage
+- Test model creation
+- Test field validation
+- Test update functionality
+- Test edge cases
+
+## 5. Build Process
+
+### 5.1 TypeScript Configuration
+- Use `tsconfig.json` for TypeScript configuration
+- Generate declaration files (`*.d.ts`) for type hints
+- Use appropriate plugins to generate declaration files during build
+
+### 5.2 Package Configuration
+- Configure `package.json` exports for different module formats
+- Include proper type definitions in exports
+- Use `pnpm` for package management
+
+### 5.3 Build Output File Extensions
+- **ESM**: `.esm.js` (ECMAScript Module)
+- **CJS**: `.cjs` (CommonJS Module)
+- **UMD**: `.umd.js` (Universal Module Definition)
+- **IIFE**: `.iife.js` (Immediately Invoked Function Expression)
+
+Example file names for a project named "project-name":
+- `project-name.esm.js`
+- `project-name.cjs`
+- `project-name.umd.js`
+- `project-name.iife.js`
+
+## 6. Dependency Management
+
+### 6.1 External Dependencies
+- Use shared utility packages for common functionality
+- Import utilities directly from packages
+
+### 6.2 Internal Dependencies
+- Use relative paths for internal imports
+- Import constants from `../../constants`
+- Organize imports logically
+
+## 7. Constants
+
+### 7.1 Constant Organization
+- Place all constants in `lib/constants/` directory
+- Group constants by domain
+- Export constants from a central index file
+
+### 7.2 Constant Usage
+- Use constants instead of hardcoded strings
+- Maintain consistent naming conventions for constants
+
+Example:
+```typescript
+// Instead of using hardcoded strings:
+if (status === 'active') {
+  // logic
+}
+
+// Use constants:
+const STATUS = {
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+  PENDING: 'pending'
+}
+
+if (status === STATUS.ACTIVE) {
+  // logic
+}
+```
+
+## 8. Error Handling
+
+### 8.1 Validation
+- Implement validation logic in model classes
+- Use consistent patterns for indicating invalid models
+- Use `isValid` property for model validation
+- Return null from `init()` method for invalid models
+
+### 8.2 Error Reporting
+- Use descriptive error messages
+- Log errors appropriately
+- Handle edge cases gracefully
+
+## 9. Performance
+
+### 9.1 Code Optimization
+- Use efficient algorithms
+- Avoid unnecessary computations
+- Use proper data structures
+
+### 9.2 Build Optimization
+- Use Vite for fast builds
+- Configure build options for different module formats
+- Generate optimized bundles
+
+## 10. Documentation
+
+### 10.1 Code Comments
+- Add comments for complex logic
+- Document public methods and properties
+- Explain design decisions
+
+### 10.2 Project Documentation
+- Maintain this best practices document
+- Update documentation when adding new features
+- Document breaking changes
+
+## 11. Build Tool Migration (Optional)
+
+This section is only necessary for projects with existing Webpack, Gulp, or Mocha setups. If you're starting a new project, you can skip this section and directly use Vite and Vitest.
+
+### 11.1 Considerations for Migration
+
+#### Key Steps
+- Update package.json to remove Webpack, Gulp, and Mocha dependencies
+- Add Vite, Vitest, and related plugin dependencies
+- Update scripts to use Vite for building and Vitest for testing
+- Configure build output formats and type definitions
+- Remove Webpack and Gulp configuration files
+- Verify the migration works correctly
+
+#### Benefits of Migrating to Vite and Vitest
+- Faster build times compared to Webpack
+- Modern, actively maintained tooling ecosystem
+- Simplified configuration compared to Webpack
+- Better TypeScript support
+- Integrated testing with Vitest
+- Consistency across Questwork projects
+
+### 11.2 Core Configuration Elements
+
+When setting up Vite and Vitest, ensure to include:
+- Build configuration for multiple output formats (ESM, CJS, UMD, IIFE)
+- Type declaration file generation
+- Test configuration with appropriate environment setup
+- Proper external dependency handling

package/BUILDING_JS_TS_LIBRARY.md

@@ -0,0 +1,321 @@
+# Building a JavaScript + TypeScript Library
+
+This guide outlines the best practices for building a library that supports both JavaScript and TypeScript, based on the approaches used in the `qw.q.utilities` and `qw.q.ecoffice.model` projects.
+
+## Table of Contents
+
+1. [Project Setup](#project-setup)
+2. [Code Structure](#code-structure)
+3. [TypeScript Configuration](#typescript-configuration)
+4. [Build Process](#build-process)
+5. [Package Configuration](#package-configuration)
+6. [Testing](#testing)
+7. [Publishing](#publishing)
+8. [Best Practices Reference](#best-practices-reference)
+
+## 1. Project Setup
+
+### 1.1 Initialize Project
+
+```bash
+# Create project directory
+mkdir my-library
+cd my-library
+
+# Initialize with pnpm
+pnpm init
+
+# Install dependencies
+pnpm add -D typescript vite vitest vite-plugin-dts
+```
+
+### 1.2 Directory Structure
+
+```
+my-library/
+├── lib/                 # Source code
+│   ├── helpers/         # Utility functions
+│   ├── models/          # Data models
+│   ├── index.ts         # Main entry point
+├── dist/                # Build output
+├── package.json         # Package configuration
+├── tsconfig.json        # TypeScript configuration
+├── vite.config.js       # Vite build configuration
+├── vitest.config.js     # Vitest configuration
+```
+
+## 2. Code Structure
+
+### 2.1 Main Entry Point
+
+Create a TypeScript entry point that exports all modules:
+
+```typescript
+// lib/index.ts
+export * from './helpers/index.js';
+export * from './models/index.js';
+```
+
+### 2.2 Export Patterns
+
+- Place all exports at the bottom of the file
+- Separate named exports from type exports
+- Use consistent naming conventions
+
+## 3. TypeScript Configuration
+
+### 3.1 tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "allowJs": true,
+    "checkJs": false,
+    "jsx": "preserve",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./lib",
+    "strict": false,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "lib/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}
+```
+
+## 4. Build Process
+
+### 4.1 Vite Configuration
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import path from 'path';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  plugins: [
+    dts({
+      include: ['lib/**/*.js', 'lib/**/*.ts'],
+      exclude: ['**/*.spec.js', '**/*.spec.ts'],
+      rollupTypes: true,
+      outDir: 'dist',
+      rootDir: 'lib',
+    }),
+  ],
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+    lib: {
+      entry: path.resolve(__dirname, 'lib/index.ts'),
+      name: 'MyLibrary',
+      fileName: (format) => {
+        if (format === 'es') return 'my-library.esm.js';
+        if (format === 'cjs') return 'my-library.cjs';
+        if (format === 'umd') return 'my-library.umd.js';
+        return `my-library.${format}.js`;
+      },
+    },
+    rollupOptions: {
+      external: [], // Add external dependencies here
+      output: [
+        {
+          format: 'es',
+          generatedCode: 'es2015',
+          exports: 'named',
+        },
+        {
+          format: 'cjs',
+          exports: 'named',
+        },
+        {
+          format: 'umd',
+          name: 'MyLibrary',
+          exports: 'named',
+        },
+        {
+          format: 'iife',
+          name: 'MyLibrary',
+          exports: 'named',
+        },
+      ],
+    },
+  },
+  test: {
+    environment: 'node',
+    coverage: {
+      reporter: ['text', 'html'],
+    },
+    globals: true,
+    setupFiles: ['lib/test.setup.js'],
+    mocha: {
+      ui: 'bdd',
+    },
+  },
+});
+```
+
+### 4.2 Build Scripts
+
+Add build scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run"
+  }
+}
+```
+
+## 5. Package Configuration
+
+### 5.1 package.json
+
+```json
+{
+  "name": "my-library",
+  "version": "1.0.0",
+  "description": "My JavaScript + TypeScript library",
+  "type": "module",
+  "exports": {
+    ".": {
+      "require": "./dist/my-library.cjs",
+      "import": "./dist/my-library.esm.js",
+      "default": "./dist/my-library.umd.js",
+      "types": "./dist/my-library.d.ts"
+    }
+  },
+  "types": "./dist/my-library.d.ts",
+  "main": "./dist/my-library.cjs",
+  "module": "./dist/my-library.esm.js",
+  "unpkg": "./dist/my-library.umd.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vite": "^5.4.10",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^2.1.4"
+  }
+}
+```
+
+## 6. Testing
+
+### 6.1 Test Setup
+
+Use Vitest for testing. Place test files next to the corresponding source files with `.spec.ts` extension:
+
+```typescript
+// lib/models/myModel.spec.ts
+import { expect } from 'chai';
+import { MyModel } from './myModel.js';
+
+describe('MyModel', () => {
+  it('should create a valid model', () => {
+    const model = MyModel.init({ name: 'Test' });
+    expect(model.isValid).to.be.true;
+  });
+});
+```
+
+## 7. Publishing
+
+### 7.1 Build and Publish
+
+```bash
+# Build the library
+pnpm run build
+
+# Publish to npm
+pnpm publish
+```
+
+## 8. Best Practices Reference
+
+### 8.1 From qw.q.ecoffice.model/best_practices.md
+
+#### 8.1.1 Build Output File Extensions
+
+- **ESM**: `.esm.js` (ECMAScript Module)
+- **CJS**: `.cjs` (CommonJS Module)
+- **UMD**: `.umd.js` (Universal Module Definition)
+- **IIFE**: `.iife.js` (Immediately Invoked Function Expression)
+
+#### 8.1.2 TypeScript Configuration
+- Use `tsconfig.json` for TypeScript configuration
+- Generate declaration files (`*.d.ts`) for type hints
+- Use `vite-plugin-dts` to generate declaration files during build
+
+#### 8.1.3 Package Configuration
+- Configure `package.json` exports for different module formats
+- Include proper type definitions in exports
+- Use `pnpm` for package management
+
+#### 8.1.4 Code Structure
+- **Models**: Place all data models in `lib/models/` directory
+- **Helpers**: Place utility functions in `lib/helpers/` directory
+- **Tests**: Place unit tests next to the corresponding model files with `.spec.ts` extension
+
+#### 8.1.5 Testing
+- Use Vitest for unit testing
+- Place test files next to the corresponding model files
+- Use descriptive test names
+- Test both success and failure cases
+
+## 9. Example Projects
+
+- **qw.q.utilities**: A utility library with TypeScript support
+- **qw.q.ecoffice.model**: A data model library with TypeScript support
+
+## 10. Troubleshooting
+
+### 10.1 Common Issues
+
+#### 10.1.1 Circular Dependencies
+
+- Avoid circular dependencies by importing directly from specific files instead of index files
+- Use forward references when necessary
+
+#### 10.1.2 Declaration File Generation
+
+- Ensure `vite-plugin-dts` is properly configured
+- Use a TypeScript entry point for better type analysis
+- Check that all exports are properly typed
+
+#### 10.1.3 Module Resolution
+
+- Use proper file extensions in imports (e.g., `.js` for ESM even when importing from `.ts` files)
+- Configure `package.json` exports correctly for different module formats
+
+## 11. Conclusion
+
+Building a JavaScript + TypeScript library requires careful configuration of TypeScript, Vite, and package.json. By following the best practices outlined in this guide and referencing the `qw.q.ecoffice.model` project, you can create a robust library that provides excellent type support for TypeScript users while remaining compatible with JavaScript users.
+
+Key takeaways:
+- Use TypeScript for the main entry point
+- Configure Vite to generate multiple module formats
+- Use `vite-plugin-dts` to generate declaration files
+- Configure `package.json` exports for different module formats
+- Include proper type definitions in the package configuration
+- Test both TypeScript and JavaScript usage