Node.js Library Development

Development guidelines for TypeScript-based Node.js libraries using Bun package manager. Emphasizes strict typing, loose coupling, comprehensive testing, and structured planning before implementation.

Project Context

This skill is designed for TypeScript-based Node.js library projects that will be shared across multiple projects and published to GitHub Package Registry.

**Technology Stack:**

TypeScript Development Standards

Strict TypeScript Configuration

Always use strict TypeScript settings:

```typescript

{

"strict": true,

"noImplicitAny": true,

"strictNullChecks": true,

"strictFunctionTypes": true,

"noImplicitReturns": true,

"noUnusedLocals": true,

"noUnusedParameters": true

}

```

Code Quality Rules

1. **No `any` type**: Always provide explicit types

2. **Strict null checks**: Handle null/undefined explicitly

3. **Immutable patterns**: Prefer readonly and const assertions

4. **Error handling**: Use Result/Either patterns or proper error types

5. **Dependency injection**: Use interfaces for loose coupling

6. **Split into pieces**: Break down large files into smaller, focused modules. Ideally one file per class/service. Follow existing directory structure

7. **Keep it simple**: Do not over-engineer solutions. Aim for simplicity and clarity. No functions for "just in case" scenarios

Architecture Patterns

Loose Coupling Principles

Apply these architectural principles:

1. **Dependency Inversion**: Depend on abstractions, not concretions

2. **Interface Segregation**: Create focused, single-purpose interfaces

3. **Single Responsibility**: Each module has one reason to change

4. **Repository Pattern**: Abstract data access behind interfaces

Logging

Do not include logging in library code as this is a shared library repository.

Testing Requirements

For New Code

For Refactoring/Fixes

Testing Pattern

Use dependency injection for testability:

```typescript

describe('SearchService', () => {

let service: SearchService;

let mockRepo: jest.Mocked<IRepository>;

let mockVectorStore: jest.Mocked<IVectorStore>;

beforeEach(() => {

mockRepo = createMockRepository();

mockVectorStore = createMockVectorStore();

service = new SearchService(mockRepo, mockVectorStore);

});

describe('search', () => {

it('should function correctly', async () => {

// test main functionality

});

it('should handle empty results gracefully', async () => {

// Test edge cases

});

it('should handle service errors', async () => {

// Test error conditions

});

});

});

```

Development Workflow

**ALWAYS follow these steps for any code addition or modification:**

Step 1: Build a Plan

Before implementing, create a detailed plan including:

**Example Plan Format:**

```markdown

Implementation Plan

Objective

Implement hybrid search endpoint combining semantic and metadata filtering

Components Affected

New Interfaces

Dependencies

Testing Strategy

```

Step 2: Get User Confirmation

Step 3: Implement

Proceed with implementation according to the approved plan.

Step 4: Add Unit Tests

Write unit tests for all new functionality, including edge cases and error conditions.

Step 5: Provide Implementation Summary

After implementation, provide a comprehensive summary:

```markdown

Implementation Summary

Files Added/Modified

Key Features Implemented

Breaking Changes

Next Steps

Testing Results

```

Domain-Specific Guidelines

API Design

Input Validation

Security Guidelines

Key Principles

Every piece of code should be:

When in doubt, favor explicit types and clear interfaces over clever implementations.