tiny-pattern-ts/project-specs.md

Project Specifications for TypeScript NPM Module

• name of package: tiny-pattern-ts

0. References

typescript-lib-starter-tiny => https://github.com/tmueller/typescript-lib-starter-tiny/

1. Development Environment

• TypeScript: Use strictest rules (via npm package "@tsconfig/strictest", additional strictures)

• EditorConfig: Use .editorconfig from typescript-lib-starter-tiny

• Prettier: For code formatting, integrated with ESLint

• ESLint: Strictest type-checked rules, integrated with Prettier

• Import Sorting: Via Prettier or ESLint

• cspell: Basic spelling configuration

• Lefthook: Pre-commit checks for:

  • Type checking
  • Spelling
  • Package sorting
  • Linting
  • Formatting
  • Outdated Packages

• Additional Dev Dependencies:

  • lefthook
  • sort-package-json
  • check-outdated

2. Build & Test

• Build Tool: Vite (ESM only, no CJS)
• Testing: Vitest
• TypeScript Build Output: dist directory
• Additional Runtime Dependencies:
  • tslib
  • type-fest

3. Project Structure & Files

• .gitignore: Ignore dist, node_modules, and other common files
• .npmignore: Ignore src and other non-dist files
• LICENSE: MIT
• README.md: Scaffolded
• commit-message-template: From typescript-lib-starter-tiny
• Target Environments: Browser and latest LTS Node.js
• No React, No CJS, ESM only

4. Automation & Quality

• Version Automation: Use standard npm version for versioning
• Unused Dependency Check: Use check-outdated with config
• No commitlint, no conventional commits

5. Scripts (Clustered as in typescript-lib-starter-tiny, named similarly)

SETUP

• use:git-commit-message: Set up commit message template (if needed)

TEST

• test: Run typecheck and all tests
• test:unit: Run unit tests with Vitest
• test:ci: Run tests in CI mode (with coverage, fail-fast)

BUILD

• build: Build the project using Vite

CLEAN

• clean: Clean build output
• clean:build: Remove dist directory

CHECK

• check: Run all checks (lint, spell, typecheck, import/package sort, outdated)
• check:eslint: Run ESLint
• check:prettier: Check formatting with Prettier
• check:cspell: Run cspell
• check:tsc: TypeScript typecheck (no emit)
• check:package: Check package.json sort
• check:outdated: Check for unused/outdated dependencies

FIX

• fix: Run all fixers (eslint, prettier, package sort)
• fix:eslint: Auto-fix ESLint issues
• fix:prettier: Auto-fix formatting with Prettier
• fix:package: Auto-fix package.json sort

HOOKS

• Lefthook will run relevant scripts on staged files for pre-commit (typecheck, lint, spell, sort, format, check:outdated)

---

6. Repository & CI/CD

• Repository: Hosted on GitHub
• Build Pipeline: Use GitHub Actions for CI/CD
  • On push and pull request: run build, lint, typecheck, test:ci, spell, check:outdated
  • On release (tagged commit): publish to npm

7. Versioning & Publishing

• Version Update: Use npm version to bump version after merging to main and before publishing
• Publishing to npm: Only publish from CI on tagged commits (e.g., after version bump and release notes)
• Recommended Workflow:
  1. Develop and merge PRs to main
  2. Run all checks via CI
  3. Bump version with npm version <patch|minor|major>
  4. Push tag to GitHub
  5. CI builds and publishes to npm on tag

8. NPM Keywords

• pattern-matching
• pattern
• match
• algebraic-data-types
• adt
• typescript

The library is for pattern matching (not regex), similar to F#'s pattern matching, for TypeScript/ESM environments.

9. Code Coverage

• Configuration:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    coverage: {
      reporter: ['text', 'html', 'lcov'],
      include: ['src/**/*.ts'],
      exclude: ['src/**/*.test.ts', 'test/**'],
    },
  },
});

• Coverage reports: text summary, HTML, and lcov formats

• Add coverage thresholds if desired

• CI: Ensure coverage is generated and optionally uploaded as an artifact or checked for minimum thresholds

10. Source Structure & Tree Shaking

• Source Directory: All source code resides in src/ and is exported via src/index.ts.
• Configuration:
  • Ensure sideEffects: false in package.json
  • Use ESM-only exports
  • Avoid top-level side effects in modules
  • Prefer explicit exports in index.ts for best results
• the human will implement the source code

11. Included Templates from typescript-lib-starter-tiny

.editorconfig

# Editor configuration, see http://editorconfig.org
root = true

[*]
charset = utf-8
indent_style = space
indent_size = 4
insert_final_newline = true
max_line_length = 80
trim_trailing_whitespace = true
quote_type = double

[*.md]
max_line_length = 0
trim_trailing_whitespace = false

[COMMIT_EDITMSG]
max_line_length = 0

commit-message-template

# If applied, this commit will... (Max 50 char)


# Explain why this change is being made (Max 72 Char) [WHAT and WHY vs HOW]


# Provide links or keys to any relevant tickets, articles or other resources
Resolves #...

# --- COMMIT END ---
# Remember to
#    Use the imperative mood in the subject line
#    Capitalize the subject line
#    Do not end the subject line with a period
#    Separate subject from body with a blank line
#    Use the body to explain what and why vs. how
#    Can use multiple lines with "-" for bullet points in body

README.md Structure (to scaffold)

• Project title and description
• Development
  • Build: npm run build
  • Test: npm run test, npm run test:ci
  • Checks: npm run check, npm run fix
• VSCode integration
  • Debugging
  • Running tests
• Document workflows like
  • Version updates
  • Changelog automation
  • Publishing
• Contribution guidelines
  • Commit signing (GPG)
  • How to set up commit message template
  • Reference to commit-message-template

12. Project Initialization & Commit Strategy

• Start by initilizing git with a main branch
• Initial commit: add an empty README.md
• create a feature branch: feature/setup
• For each technology or tool added (and its configuration), create a separate commit:
  • Prepend each commit message with a matching gitmoji (e.g., ✨ for new features, 🔧 for config, etc.)
  • Example commit messages:
    • 🎉 Initial commit with empty README
    • ✨ Configured Vite (Vite-specific setup)
    • ✨ Configured TypeScript (may be merged with Vite if dependent)
    • 🔧 Configured ESLint
    • 🔧 Configured Prettier
    • ...and so on for each technology/tool
• Each commit should include only the relevant files and configuration for that technology/tool
• This approach ensures a clean, understandable project history and makes it easy to review or revert specific setup steps

13. Changelog Automation

• Use a tool like standard-version or changesets to automate changelog generation from commit messages or PRs.
• Ensure changelog is updated as part of the release process.

14. Publishing Public

• Configure npm publishing to be public by default.
• Add "publishConfig": { "access": "public" } to package.json.
• Ensure CI/CD pipeline publishes with public access.

15. VSCode Integration

• Add a .vscode/settings.json with the following content:

{
    "typescript.tsdk": "node_modules/typescript/lib",
    "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "[json]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "[mdx]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    },
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true,
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
    }
}

• Add .vscode/extensions.json with recommended extensions:

  • esbenp.prettier-vscode (Prettier)
  • dbaeumer.vscode-eslint (ESLint)
  • streetsidesoftware.code-spell-checker (cspell)
  • vitest.explorer (for test integration)
  • ms-vscode.vscode-typescript-next (for latest TS features, optional)

• Add .vscode/tasks.json for common tasks (optional):

  • Build, test, lint, typecheck, format, spell, check:outdated

• Ensure VSCode uses workspace TypeScript version and Prettier for formatting