Skip to content

dev-cycle-instructions.md

Latest commit

 

History

History
285 lines (198 loc) · 5.48 KB

dev-cycle-instructions.md

File metadata and controls

285 lines (198 loc) · 5.48 KB

Development Cycle Instructions

This document outlines the standard development workflow for @oresoftware/linked-queue.

Standard Development Workflow

1. Pre-Development Setup

# Install dependencies
npm install

# Compile TypeScript
npx tsc
# Or if npm run build is configured:
npm run build

2. Make Changes

Edit files in src/ directory:

  • src/linked-queue.ts - Main queue implementation
  • src/iterator.ts - Iterator utilities
  • src/example.ts - Example usage

3. Compile Changes

After making changes to TypeScript files:

npx tsc

Or use watch mode for automatic recompilation:

npx tsc --watch

Or if npm run build is configured:

npm run build

4. Run Tests

Test your changes:

npm test

This runs all tests in test/src/ using Suman.

5. Verify Tests Pass

Ensure all tests pass:

  • 11 JavaScript test files should pass
  • TypeScript test files may show execution warnings (expected)

6. Stage and Commit Changes

# Stage all changes
git add -A

# Commit with descriptive message
git commit -m "Description of changes"

7. Push to Remote

git push

Complete Development Cycle

Here's the complete cycle in one flow:

# 1. Install/update dependencies
npm install

# 2. Compile TypeScript
npx tsc
# Or: npm run build

# 3. Run tests
npm test

# 4. If tests pass, commit
git add -A
git commit -m "Your commit message"
git push

Full Cycle Checklist

  • Make code changes in src/
  • Run npx tsc or npm run build to compile
  • Run npm test to verify tests pass
  • Run npm install --save-dev . to update local package (if needed)
  • Test both CommonJS and ESM imports work (if ESM is configured)
  • Commit changes
  • Push to remote

Testing Workflow

Run All Tests

npm test

Run Specific Test File

npx suman test/src/basic-queue.test.js

Run Individual Test Files

node test/src/simple.js
node test/src/basic-queue.test.js

Fuzz Tests

The fuzz tests run 1,000,000 iterations to stress test the queue:

  • test/src/basic-queue-fuzz.js
  • test/src/linked-queue-fuzz.js
  • test/src/queue-fuzz.js

Test Results

Expected results:

  • ✅ 11 JavaScript tests passing
  • ⚠️ 3 TypeScript files (source files, not executable)

Module Support

This package supports:

  • CommonJS: require('@oresoftware/linked-queue')
  • ES Modules: import {LinkedQueue} from '@oresoftware/linked-queue' (if ESM build is configured)

The exports field in package.json automatically selects the correct format (if configured).

Code Quality Checks

Type Checking

TypeScript compiler performs type checking during compilation:

npx tsc --noEmit

This checks types without generating output files.

Linting

Check for linting errors (if configured):

# Check if linter is configured
npm run lint  # if available

Build Process

Production Build

  1. Clean previous build:

    rm -rf dist/

  2. Compile:

    npx tsc
# Or: npm run build

  3. Verify output:

    ls -la dist/

Development Build

Use watch mode for continuous compilation:

npx tsc --watch

Version Management

Update Version

Edit package.json:

{
  "version": "2.1.130"  // increment version
}

Tag Release

After committing version bump:

git tag v2.1.130
git push --tags

Troubleshooting

Tests Failing

  1. Check compilation errors:

    npx tsc

  2. Verify test files are in test/src/

  3. Check import paths in test files

  4. Ensure npm run build completed successfully (if configured)

  5. Run npm install --save-dev . to update local package

  6. Check that both dist/ and dist/esm/ directories exist (if ESM is configured)

Compilation Errors

  1. Check tsconfig.json configuration (and tsconfig.esm.json if ESM is configured)
  2. Verify all dependencies are installed: npm install
  3. Check TypeScript version compatibility
  4. Run npx tsc --noEmit to check for type errors

Import Errors

  1. Ensure dist/ directory exists and contains compiled files
  2. Verify package.json main/types fields point to correct files
  3. Check import paths in consuming code
  4. Verify package.json has correct exports field (if ESM is configured)
  5. Check main, module, and types fields are set correctly
  6. Ensure files field includes dist directory

Module Resolution Issues

  1. Verify package.json has correct exports field (if ESM is configured)
  2. Check main, module, and types fields are set correctly
  3. Ensure files field includes dist directory

Best Practices

  1. Always compile before committing: Run npx tsc to ensure no compilation errors
  2. Run tests before pushing: Ensure npm test passes
  3. Write descriptive commit messages: Explain what and why
  4. Keep tests updated: Update tests when adding new features
  5. Follow TypeScript best practices: Use proper types, avoid any where possible

Quick Reference

Task Command
Install dependencies npm install
Compile TypeScript npx tsc
Watch mode npx tsc --watch
Run tests npm test
Stage changes git add -A
Commit git commit -m "message"
Push git push

Continuous Integration

The project may use CI/CD. Common checks:

  • TypeScript compilation
  • Test execution
  • Code quality checks

Ensure local development matches CI requirements.