@geekmidas/services

Service discovery and dependency injection system for TypeScript applications with full type safety and automatic lifecycle management.

Features

- Type-Safe Services: Full TypeScript support with generic type inference
- Lazy Initialization: Services are initialized only when needed
- Singleton Pattern: Services are cached and reused across requests
- Dependency Injection: Automatic service resolution and injection
- Environment Integration: Seamless integration with @geekmidas/envkit
- Service Discovery: Centralized service registry and discovery
- Error Handling: Graceful error handling during service initialization

Installation

``bash
pnpm add @geekmidas/services
`

Quick Start

$3

`typescript
import type { Service } from '@geekmidas/services';
import type { EnvironmentParser } from '@geekmidas/envkit';
import { Kysely } from 'kysely';

// Define your database service
const databaseService = {
serviceName: 'database' as const,
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
url: get('DATABASE_URL').string(),
ssl: get('DATABASE_SSL').string().transform(Boolean).default('false')
})).parse();

const db = new Kysely({ / config / });
await db.connection().execute('SELECT 1'); // Health check

return db;
}
} satisfies Service<'database', Kysely>;

export { databaseService };
`

$3

`typescript
import { e } from '@geekmidas/constructs/endpoints';
import { databaseService } from './services/database';
import { z } from 'zod';

export const getUser = e
.get('/users/:id')
.params(z.object({ id: z.string() }))
.services([databaseService])
.handle(async ({ params, services }) => {
// services.database is fully typed as Kysely
const user = await services.database
.selectFrom('users')
.where('id', '=', params.id)
.selectAll()
.executeTakeFirstOrThrow();

return user;
});
`

Service Discovery

The ServiceDiscovery class manages service lifecycle and dependency injection:

`typescript
import { ServiceDiscovery } from '@geekmidas/services';
import { ConsoleLogger } from '@geekmidas/logger/console';
import { EnvironmentParser } from '@geekmidas/envkit';

const logger = new ConsoleLogger();
const envParser = new EnvironmentParser(process.env).create(() => ({})).parse();

const serviceDiscovery = ServiceDiscovery.getInstance(logger, envParser);

// Services are lazily initialized
const database = await serviceDiscovery.discover(databaseService);
`

Creating Services

$3

`typescript
import type { Service } from '@geekmidas/services';
import { Kysely, PostgresDialect } from 'kysely';
import { Pool } from 'pg';

const databaseService = {
serviceName: 'database' as const,
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
host: get('DB_HOST').string(),
port: get('DB_PORT').string().transform(Number).default('5432'),
database: get('DB_NAME').string(),
user: get('DB_USER').string(),
password: get('DB_PASSWORD').string(),
ssl: get('DB_SSL').string().transform(Boolean).default('false')
})).parse();

const db = new Kysely({
dialect: new PostgresDialect({
pool: new Pool({
host: config.host,
port: config.port,
database: config.database,
user: config.user,
password: config.password,
ssl: config.ssl
})
})
});

return db;
}
} satisfies Service<'database', Kysely>;
`

$3

`typescript
import type { Service } from '@geekmidas/services';
import { UpstashCache } from '@geekmidas/cache/upstash';

const cacheService = {
serviceName: 'cache' as const,
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
url: get('UPSTASH_REDIS_URL').string().url(),
token: get('UPSTASH_REDIS_TOKEN').string()
})).parse();

return new UpstashCache({
url: config.url,
token: config.token
});
}
} satisfies Service<'cache', UpstashCache>;
`

$3

`typescript
import type { Service } from '@geekmidas/services';
import { createEmailClient } from '@geekmidas/emailkit';
import * as templates from './email-templates';

const emailService = {
serviceName: 'email' as const,
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
host: get('SMTP_HOST').string(),
port: get('SMTP_PORT').string().transform(Number),
user: get('SMTP_USER').string(),
pass: get('SMTP_PASS').string(),
from: get('EMAIL_FROM').string().email()
})).parse();

return createEmailClient({
smtp: {
host: config.host,
port: config.port,
auth: {
user: config.user,
pass: config.pass
}
},
templates,
defaults: { from: config.from }
});
}
} satisfies Service<'email', ReturnType>;
`

$3

`typescript
import type { Service } from '@geekmidas/services';
import type { EventPublisher, PublishableMessage } from '@geekmidas/events';

type UserEvents =
| PublishableMessage<'user.created', { userId: string }>
| PublishableMessage<'user.updated', { userId: string }>;

const userEventPublisher = {
serviceName: 'userEventPublisher' as const,
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
publisherUrl: get('EVENT_PUBLISHER_URL').string()
})).parse();

const { Publisher } = await import('@geekmidas/events');
return Publisher.fromConnectionString(config.publisherUrl);
}
} satisfies Service<'userEventPublisher', EventPublisher>;
`

Multiple Services

Inject multiple services into a construct:

`typescript
import { e } from '@geekmidas/constructs/endpoints';
import { databaseService } from './services/database';
import { cacheService } from './services/cache';
import { emailService } from './services/email';
import { z } from 'zod';

export const createUser = e
.post('/users')
.body(z.object({
name: z.string(),
email: z.string().email()
}))
.services([databaseService, cacheService, emailService])
.handle(async ({ body, services }) => {
// Check cache first
const cached = await services.cache.get(user:${body.email});
if (cached) {
return cached;
}

// Create user in database
const user = await services.database
.insertInto('users')
.values(body)
.returningAll()
.executeTakeFirstOrThrow();

// Send welcome email
await services.email.sendTemplate('welcome', {
to: user.email,
props: { name: user.name }
});

// Cache result
await services.cache.set(user:${user.email}, user, 3600);

return user;
});
`

Service Lifecycle

$3

Services are only initialized when first requested:

`typescript
const serviceDiscovery = ServiceDiscovery.getInstance(logger, envParser);

// Not initialized yet
const service1 = databaseService;

// Initialized here
const db = await serviceDiscovery.discover(databaseService);

// Reuses same instance (singleton)
const db2 = await serviceDiscovery.discover(databaseService);
assert(db === db2); // true
`

$3

ServiceDiscovery ensures each service is a singleton:

`typescript
// First call initializes the service
const db1 = await serviceDiscovery.discover(databaseService);

// Subsequent calls return cached instance
const db2 = await serviceDiscovery.discover(databaseService);
const db3 = await serviceDiscovery.discover(databaseService);

// All references point to same instance
console.log(db1 === db2 && db2 === db3); // true
`

Error Handling

Handle service initialization errors gracefully:

`typescript
const databaseService = {
serviceName: 'database' as const,
async register(envParser: EnvironmentParser<{}>) {
try {
const config = envParser.create((get) => ({
url: get('DATABASE_URL').string()
})).parse();

const db = new Kysely({ / config / });

// Test connection
await db.connection().execute('SELECT 1');

return db;
} catch (error) {
throw new Error(Failed to initialize database: ${error.message});
}
}
} satisfies Service<'database', Kysely>;
`

Testing

Mock services in tests:

`typescript
import { ServiceDiscovery } from '@geekmidas/services';
import { vi } from 'vitest';

// Create mock database
const mockDb = {
selectFrom: vi.fn(() => ({
where: vi.fn(() => ({
selectAll: vi.fn(() => ({
executeTakeFirstOrThrow: vi.fn().mockResolvedValue({
id: '1',
name: 'Test User'
})
}))
}))
}))
};

// Create mock service
const mockDatabaseService = {
serviceName: 'database' as const,
async register() {
return mockDb;
}
} satisfies Service<'database', typeof mockDb>;

// Use in tests
const serviceDiscovery = ServiceDiscovery.getInstance(logger, envParser);
const db = await serviceDiscovery.discover(mockDatabaseService);

// Test your code
`

Service Patterns

$3

`typescript
import type { Service } from '@geekmidas/services';

class UserRepository {
constructor(private db: Kysely) {}

async findById(id: string) {
return this.db
.selectFrom('users')
.where('id', '=', id)
.selectAll()
.executeTakeFirst();
}

async create(data: NewUser) {
return this.db
.insertInto('users')
.values(data)
.returningAll()
.executeTakeFirstOrThrow();
}
}

const userRepositoryService = {
serviceName: 'userRepository' as const,
async register(envParser: EnvironmentParser<{}>) {
const db = await databaseService.register(envParser);
return new UserRepository(db);
}
} satisfies Service<'userRepository', UserRepository>;
`

$3

`typescript
import type { Service } from '@geekmidas/services';

class UserService {
constructor(
private repository: UserRepository,
private email: EmailClient,
private cache: Cache
) {}

async createUser(data: NewUser) {
const user = await this.repository.create(data);
await this.email.sendTemplate('welcome', {
to: user.email,
props: { name: user.name }
});
await this.cache.set(user:${user.id}, user, 3600);
return user;
}
}

const userServiceService = {
serviceName: 'userService' as const,
async register(envParser: EnvironmentParser<{}>) {
const repository = await userRepositoryService.register(envParser);
const email = await emailService.register(envParser);
const cache = await cacheService.register(envParser);

return new UserService(repository, email, cache);
}
} satisfies Service<'userService', UserService>;
`

TypeScript Types

`typescript
import type { Service } from '@geekmidas/services';

// Service interface
interface Service {
serviceName: TName;
register(envParser: EnvironmentParser<{}>): Promise | TInstance;
}

// Infer service name
type ServiceName = T extends Service ? N : never;

// Infer service instance type
type ServiceInstance = T extends Service ? I : never;
`

Best Practices

$3

`typescript
// ✅ Use satisfies to ensure correct implementation
const service = {
serviceName: 'myService' as const,
async register(envParser) {
return new MyService();
}
} satisfies Service<'myService', MyService>;

// ❌ Don't use type annotation (loses type inference)
const service: Service = {
serviceName: 'myService',
async register(envParser) {
return new MyService();
}
};
`

$3

`typescript
// ✅ Literal type for better type inference
serviceName: 'database' as const

// ❌ String type loses specificity
serviceName: 'database'
`

$3

`typescript
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
url: get('DATABASE_URL').string().url(), // Validates URL format
port: get('PORT').string().transform(Number).default('5432'),
ssl: get('SSL').string().transform(Boolean).default('false')
})).parse();

return new Database(config);
}
`

$3

`typescript
async register(envParser: EnvironmentParser<{}>) {
const db = new Database(config);

// Test connection during initialization
await db.connection().execute('SELECT 1');

return db;
}
``

Related Packages

- @geekmidas/constructs - Uses services for dependency injection
- @geekmidas/envkit - Environment configuration for services
- @geekmidas/logger - Logging within services
- @geekmidas/cache - Cache services
- @geekmidas/events - Event publisher services

License

MIT