@expressive-tea/core

v2.0.1

Published

9 days ago

A modern TypeScript-first framework for building scalable Node.js applications with clean architecture, dependency injection, and decorator-driven development

[!IMPORTANT]
📦 Package Renamed: @expressive-tea/core
Expressive Tea has a new home on npm! Starting with v2.0.0, install using:
npm install @expressive-tea/core
Legacy package @zerooneit/expressive-tea will be maintained until April 30, 2026 for security patches only. Please migrate to @expressive-tea/core as soon as possible.
Why the change?
✨ Better namespace organization (@expressive-tea/*)
🌍 Community-focused ownership
🚀 Clearer project identity
Migration is simple: Just update your package.json and imports remain the same!
- "dependencies": { "@zerooneit/expressive-tea": "^1.2.0" }
+ "dependencies": { "@expressive-tea/core": "^2.0.0" }

[!CAUTION]
⚠️ CRITICAL: v1.x Security Notice
All versions 1.x are DEPRECATED and UNSUPPORTED as of January 27, 2026.
v1.3.x Beta - 🔴 CRITICAL SECURITY VULNERABILITY - DO NOT USE
Contains critical cryptography flaws in Teapot/Teacup gateway. If you're using this, STOP IMMEDIATELY and upgrade to v2.0.0.
v1.2.x Production - 🟡 No crypto issues, but deprecated (InversifyJS v6 EOL)
👉 Upgrade to v2.0.0 NOW - See Migration Guide

⚡ Quick Start

# Install the new package
npm install @expressive-tea/core

# Or with yarn
yarn add @expressive-tea/core

import { ServerSettings, Route, Get, Boot } from '@expressive-tea/core';

@ServerSettings({ port: 3000 })
class App extends Boot {}

@Route('/hello')
class HelloController {
  @Get('/')
  sayHello() {
    return { message: 'Hello, World! 🍵' };
  }
}

new App().start();
// 🎉 Server running on http://localhost:3000

Try it live on CodeSandbox →

🎯 Why Expressive Tea?

The Problem

Building Node.js applications is powerful, but messy. You get a blank canvas with Express—no structure, no conventions, just middleware chaos. Sound familiar?

The Solution

Expressive Tea brings the elegance of modern frameworks to Node.js, without the bloat. Think NestJS simplicity meets Express flexibility.

🌟 What Makes It Special

| Feature | What You Get | |---------|-------------| | 🎨 Clean Architecture | Decorators organize your code beautifully—no more spaghetti routes | | 🔌 Plugin Everything | Share database configs, auth, websockets across projects | | 💉 Smart DI | Singleton, Transient, Scoped services—InversifyJS under the hood | | 🛡️ Type-Safe | Full TypeScript strict mode—catch bugs before they ship | | 🔒 Secure by Default | AES-256-GCM + HKDF crypto, built-in security best practices | | ⚡ Production Ready | 92%+ test coverage, battle-tested in real applications | | 🎯 Express Compatible | Use ANY Express middleware—gradual migration friendly | | 📦 Zero Lock-in | BYOA (Bring Your Own Architecture)—we don't force opinions |

🚀 What's New in v2.0

Major security and architecture improvements!

+ ✅ Security: Fixed critical crypto vulnerabilities (AES-256-GCM + HKDF)
+ ✅ Type Safety: Full TypeScript strict mode support
+ ✅ DI: Scoped dependency injection (Singleton/Transient/Scoped)
+ ✅ Health Checks: Built-in health endpoints for Kubernetes/monitoring
+ ✅ Environment: .env file support with @Env decorator
+ ✅ Performance: Native utilities, removed lodash dependencies
+ ✅ ESLint: Migrated to ESLint v9 flat config
+ ✅ Quality: 95%+ coverage, all tests passing

⚠️ Breaking Changes:

Cryptography format changed (must re-encrypt data)
TypeScript strict mode enabled
Node.js 20+ required (Node.js 18 reached EOL April 2025)
Express 5.x required
ESLint v9 (flat config)

📖 Full Changelog • 🔄 Migration Guide

💡 Features That'll Make You Smile

🎨 Decorator-Driven Development

@Route('/api/users')
class UserController {
  @Get('/:id')
  async getUser(@Param('id') id: string) {
    return this.userService.findById(id);
  }

  @Post('/')
  async createUser(@Body() data: CreateUserDto) {
    return this.userService.create(data);
  }
}

🔌 Pluggable Architecture

import { AuthPlugin } from '@my-org/auth-plugin';
import { DatabasePlugin } from '@my-org/db-plugin';

@ServerSettings({
  port: 3000,
  plugins: [AuthPlugin, DatabasePlugin]
})
class App extends Boot {}

💉 Dependency Injection

@injectable()
class UserService {
  constructor(
    @inject(TYPES.Database) private db: Database,
    @inject(TYPES.Logger) private logger: Logger
  ) {}
}

🎯 Type-Safe Everything

// Generics everywhere
class ApiResponse<T> {
  constructor(
    public data: T,
    public status: number
  ) {}
}

@Get('/users')
getUsers(): ApiResponse<User[]> {
  return new ApiResponse(users, 200);
}

🏥 Built-in Health Checks

@HealthCheck({
  checks: [
    {
      name: 'database',
      check: async () => {
        const isConnected = await db.ping();
        return { status: isConnected ? 'pass' : 'fail' };
      },
      critical: true, // Blocks readiness probe if fails
      timeout: 5000
    }
  ]
})
class App extends Boot {}

// Endpoints:
// GET /health       - Detailed health status
// GET /health/live  - Liveness probe (K8s)
// GET /health/ready - Readiness probe (K8s)

🌍 Environment Variable Support

// Load from .env files
@Env({ path: '.env', required: ['DATABASE_URL', 'API_KEY'] })
@Env({ path: '.env.local', override: true, silent: true })
class App extends Boot {}

// In your .env:
// DATABASE_URL=postgres://localhost:5432/mydb
// API_KEY="secret-key"

🎯 Type-Safe Environment Variables (v2.0.1+)

import { z } from 'zod';

const EnvSchema = z.object({
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(32)
});

type Env = z.infer<typeof EnvSchema>;

@Env<Env>({
  transform: (env) => EnvSchema.parse(env),
  onTransformError: 'throw' // Fail fast on invalid env
})
class App extends Boot {
  constructor() {
    super();
    const env = Settings.getInstance().getEnv<Env>();
    console.log(env.PORT); // Type: number (validated!)
  }
}

📄 Configuration Files (v2.0.1+)

# .expressive-tea.yaml (YAML support!)
port: 3000
securePort: 4443

database:
  host: localhost
  port: 5432

# Comments supported!
cache:
  enabled: true
  ttl: 3600

File Priority: .expressive-tea.yaml > .expressive-tea.yml > .expressive-tea (JSON)

📦 Installation & Setup

Prerequisites

Node.js ≥ 20.0.0
TypeScript ≥ 5.0.0
Express ≥ 5.0.0

Note: Node.js 18 support was dropped in v2.0.0 as it reached End-of-Life in April 2025. We recommend using Node.js 20 LTS or Node.js 22 for the best experience and security updates.

Configure TypeScript

{
  "compilerOptions": {
    "target": "ES2017",
    "module": "commonjs",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    
    // Recommended for maximum safety
    "strict": true,
    "strictNullChecks": true,
    "noImplicitAny": true
  }
}

Install

# npm
npm install @expressive-tea/core reflect-metadata

# yarn
yarn add @expressive-tea/core reflect-metadata

Local staging with Verdaccio

If you want to test publishing locally before pushing to the public registry, use a local Verdaccio instance as a staging registry.

Quick steps:

Start Verdaccio (Docker):

docker run -d --rm --name verdaccio-expressive-tea -p 4873:4873 verdaccio/verdaccio:latest

Point npm to local registry and publish:

# point npm to local registry
npm set registry http://localhost:4873

# publish (from package root)
npm publish --registry http://localhost:4873

# restore default registry
npm set registry https://registry.npmjs.org/

Optional: Use the repo-provided Verdaccio config for deterministic behavior:

docker run -d --rm --name verdaccio-expressive-tea -p 4873:4873 \
  -v $(pwd)/.docs/verdaccio/config.yaml:/verdaccio/conf/config.yaml \
  verdaccio/verdaccio:latest

Notes:

Default URL: http://localhost:4873
Container name: verdaccio-expressive-tea (the agent checks for this name before starting a new container)
Anonymous publishing is enabled in the example config (local only). Do not expose to public networks.
The config permits overwriting the same package version for easy iterative testing.

Your First App

1. Create your server:

// server.ts
import 'reflect-metadata';
import { ServerSettings, Boot } from '@expressive-tea/core';

@ServerSettings({
  port: 3000,
  controllers: [HelloController]
})
class MyApp extends Boot {}

export default MyApp;

2. Add a controller:

// controllers/hello.controller.ts
import { Route, Get } from '@expressive-tea/core';

@Route('/hello')
export class HelloController {
  @Get('/')
  sayHello() {
    return { message: 'Hello, Expressive Tea! 🍵' };
  }
}

3. Start it up:

// main.ts
import MyApp from './server';

const app = new MyApp();
app.start().then(() => {
  console.log('🚀 Server is running!');
});

📚 Full Tutorial →

🎓 Learn More

📖 Documentation

Complete Guide - Full documentation
API Reference - Complete API docs
Examples - Sample projects

🆕 v2.0.1 Features

Configuration Files Guide - YAML/JSON config support
Environment Variables Guide - Type-safe env with Zod

🔄 Migration & Upgrading

Migration Guide v1 → v2 - Step-by-step upgrade
Release Notes v2.0 - What's new
Deprecation Notice - v1.x timeline

🛡️ Security

Security Policy - Vulnerability reporting
Changelog - Version history

🤝 Contributing

We love contributions! Whether it's bug fixes, features, or docs.

Quick links:

Contributing Guide - How to contribute
Code of Conduct - Community guidelines
Issues - Report bugs or request features

# Get started
git clone https://github.com/Expressive-Tea/expresive-tea.git
cd expresive-tea
yarn install
yarn test

🤖 AI-Assisted Development & Vibe Coding

We welcome AI-assisted contributions! Whether you're using GitHub Copilot, Cursor, Claude, or other AI coding assistants, we embrace the future of collaborative development.

⚠️ IMPORTANT: AI-Generated Code Requirements

If you're using AI tools for code generation, you MUST:

📖 Follow Repository Guidelines
- ✅ Read and strictly adhere to AGENTS.md - Agent-specific coding rules
- ✅ Read and strictly adhere to CLAUDE.md - Claude AI guidelines
- ✅ These files contain critical project conventions, style guides, and quality standards
👨‍💻 Human Review is MANDATORY
- ✅ All AI-generated code MUST be reviewed by a human developer before creating a pull request
- ✅ Understand the code completely—don't submit code you can't explain
- ✅ Test thoroughly (aim for 95%+ coverage)
- ✅ Verify the code follows our architectural patterns and best practices
✅ Quality Standards
- ✅ All tests must pass (yarn test)
- ✅ Linting must pass (yarn linter:ci)
- ✅ TypeScript must compile without errors (yarn build)
- ✅ Code must match our existing patterns and conventions
- ✅ Documentation must be updated (JSDoc, README, CHANGELOG)
📝 PR Transparency
- ✅ Disclose AI assistance in your pull request description
- ✅ Example: "This PR was developed with assistance from Claude/Copilot/Cursor"
- ✅ Highlight any sections that were fully AI-generated for extra review

Why These Rules?

🛡️ Quality Assurance - AI can make subtle mistakes humans catch
🎯 Consistency - Ensures code matches our architectural vision
📚 Knowledge Transfer - Reviewers understand your contribution
🔒 Security - Prevents AI from introducing vulnerabilities
🤝 Collaboration - Maintains clear communication in the codebase

Vibe Coding Best Practices:

// ✅ GOOD: AI-generated, reviewed, and refined by human
@Route('/api/users')
class UserController {
  @Get('/:id')
  async getUser(@Param('id') id: string): Promise<User> {
    // Human: Added validation per AGENTS.md security guidelines
    if (!id || !validator.isUUID(id)) {
      throw new BadRequestException('Invalid user ID');
    }
    return this.userService.findById(id);
  }
}

// ❌ BAD: AI-generated, unreviewed, missing error handling
@Route('/api/users')
class UserController {
  @Get('/:id')
  async getUser(@Param('id') id: string) {
    return this.userService.findById(id); // What if id is invalid?
  }
}

📚 Required Reading for AI-Assisted Development:

AGENTS.md - Repository-specific rules for AI agents
CLAUDE.md - Claude AI coding guidelines
CONTRIBUTING.md - General contribution guide
.prettierrc - Code formatting rules
eslint.config.js - Linting configuration

Questions? Ask in GitHub Discussions before submitting AI-generated code.

💬 Community & Support

Get Help

📖 Documentation
💬 Gitter Chat
📧 Email Support
🐛 GitHub Issues
🔖 Stack Overflow - Use tag expressive-tea

Stay Connected

🐦 Twitter: @expressive_tea
📧 Email: [email protected]
👨‍💻 Author: Diego Resendez

🌟 Built With

| Technology | Purpose | |------------|---------| | Express | Fast, unopinionated web framework | | TypeScript | Type-safe JavaScript | | InversifyJS | Powerful dependency injection | | Reflect Metadata | Decorator metadata support |

🏆 Sponsors

Building Expressive Tea takes time and dedication. If this project helps you, consider sponsoring!

Principal Sponsor:

Interested in sponsoring? Contact [email protected]

📄 License

Apache-2.0 License - see LICENSE file for details

📌 Versioning

We use Semantic Versioning (SemVer). See tags for available versions.

👥 Contributors

Lead Developer: Diego Resendez

See all contributors who've helped shape Expressive Tea.

❤️ Credits

Logo and banner designed by Freepik