⚠️ [Archived] ⚠️ @keminghe/npm-template

Warning

This repository is archived and no longer maintained.

• Archived: 2025-08-10 by @KemingHe
• Archive reason: moved on to more focused agentic AI development
• Inquries and corrections: email keminghe.career@gmail.com

Template for creating TypeScript utility packages for publishing to NPM registry. Social preview generated with Socialify.

⭐ Features

• 📝 Full TypeScript support with comprehensive type definitions
• ⚡️ Zero runtime dependencies with 100% test coverage
• 🔄 Automated releases with Git hooks and strict linting

📥 Installation

npm install @keminghe/npm-template

🚀 Usage

Environment Variable Utility

import { env } from '@keminghe/npm-template';

// Basic usage
// Throws runtime error if API_KEY is missing or empty
const apiKey: string = env('API_KEY');

// With default value and pattern validation
const port: string = env('PORT', {
  defaultValue: '3000',
  pattern: /^[0-9]+$/
});

String Validation

import { isNonEmptyString } from '@keminghe/npm-template';

const value = 'hello';
if (isNonEmptyString(value)) {
  // TypeScript knows value is string here
  console.log(value.toUpperCase());
}

Your Custom Utility

// Add your utility functions here
// Follow similar pattern for type safety and validation
import { YourUtility } from './your-module';

// Document clear usage examples
const result = YourUtility.process('input');

📚 API

env(name: string, options?: EnvOptions): string

Retrieves and validates an environment variable value.

Parameters:

• name - Environment variable name
• options - Optional configuration object
  • defaultValue?: string - Fallback if env var is not set
  • pattern?: RegExp - Validation pattern to test against

Returns:

• string - The validated environment variable value

Throws:

• Error if the variable is missing/empty with no default
• Error if the value doesn't match the specified pattern

// Examples
const apiKey = env('API_KEY');  // Throws if not set

const port = env('PORT', {
  defaultValue: '3000',
  pattern: /^\d+$/
});

isNonEmptyString(value: unknown): value is string

Type guard that checks if a value is a non-empty string.

Parameters:

• value - Any value to test

Returns:

• boolean - true if value is a non-empty string

const input = someValue;
if (isNonEmptyString(input)) {
  // TypeScript knows input is string here
  console.log(input.length);
}

Your Custom API

Document your new functions following this format:

/**
 * Brief description of what the function does
 * @param paramName - Parameter description
 * @returns What the function returns
 * @throws Error conditions if applicable
 */
function yourFunction(paramName: ParamType): ReturnType {
  // Implementation
}

⚙️ Development

pnpm install  # Install dependencies

pnpm test     # Run tests

pnpm build    # Build package

pnpm verify   # Full verification

🏷️ Release Process

See Tag and Publish Guide for detailed instructions on:

• Setting up GPG signing
• Creating signed Git tags
• Automatic NPM publishing via GitHub Actions

🤝 Contributing

1. Fork the repository to your GitHub account
2. Create a feature branch (git checkout -b feature/my-update)
3. Make changes and commit (git commit) with Commitizen
4. Push your changes (git push origin feature/my-update)
5. Create a Pull Request for code review

📄 License

MIT License

Copyright 2025 Keming He