@questwork/q-utilities 0.1.32 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@questwork/q-utilities",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Questwork qUtilities",
   "author": {
     "name": "Questwork Consulting Limited",

package/.github/workflows/publish.yml

@@ -1,60 +0,0 @@
-name: Publish to npm on Tag
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write  # OIDC
-    # environment: production
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0 # Needed to get tag information
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-          registry-url: https://registry.npmjs.org/
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Build
-        run: |
-          BUILD_COMMAND=$(node -p "(require('./package.json').scripts || {}).build")
-          if [ "$BUILD_COMMAND" = "undefined" ]; then
-            echo "::notice::Can't find a build script in package.json, skip."
-          else
-            pnpm run build
-          fi
-
-      # - name: Publish to npm
-      #   # if: steps.version-check.outputs.should_publish == 'true'
-      #   run: pnpm publish --no-git-checks --access public
-      #   env:
-      #     NODE_AUTH_TOKEN: ${{ secrets.QW_NPM_TOKEN }}
-          
-      - name: Update npm
-        run: |
-          NPM_VERSION=$(npm -v)
-          echo "Current npm version: $NPM_VERSION"
-          if ! npx semver -r ">=11.5.1" "$NPM_VERSION"; then
-            echo "npm version $NPM_VERSION is too old. Installing latest npm..."
-            npm install -g npm@latest
-            echo "Updated npm version: $(npm -v)"
-          fi
-
-      - name: Publish to npm
-        run: npm publish --no-git-checks --access public

package/BEST_PRACTICES.md

@@ -1,217 +0,0 @@
-# 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

@@ -1,321 +0,0 @@
-# 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