@pearl-framework/core

IoC container, Application lifecycle, and ServiceProvider base for Pearl.js

Installation

pnpm add @pearl-framework/core

Overview

@pearl-framework/core is the foundation of every Pearl app. It provides:

IoC Container — type-safe dependency injection with singleton and transient bindings
Application — bootstraps your app, registers providers, manages lifecycle
ServiceProvider — base class for organising registrations and boot logic
Config — typed configuration loader

Usage

Application bootstrap

import { Application } from '@pearl-framework/core'

const app = new Application()

app.register(DatabaseServiceProvider)
app.register(HttpServiceProvider)
app.register(AppServiceProvider)

await app.boot()

IoC Container

// Bind a singleton
app.container.singleton(Mailer, () => new Mailer(config))

// Bind a transient (new instance every time)
app.container.bind(Logger, () => new Logger())

// Resolve
const mailer = app.container.make(Mailer)

ServiceProvider

import { ServiceProvider } from '@pearl-framework/core'

export class AppServiceProvider extends ServiceProvider {
  register(): void {
    this.container.singleton(Mailer, () => new Mailer({
      driver: 'smtp',
      host: this.config.get('mail.host'),
    }))
  }

  override async boot(): Promise<void> {
    // runs after all providers are registered
  }
}

Config

import { Config } from '@pearl-framework/core'

const config = new Config({
  app: { name: 'Pearl', debug: false },
  mail: { driver: 'smtp', host: 'smtp.example.com' },
})

config.get('app.name')       // 'Pearl'
config.get('app.debug')      // false
config.get('missing', 'default') // 'default'

API

`Container`

Method	Description
`singleton(token, factory)`	Register a shared instance
`bind(token, factory)`	Register a new instance each time
`instance(token, value)`	Register an existing object
`make(token)`	Resolve a binding
`has(token)`	Check if a binding exists

`Application`

Method	Description
`register(Provider)`	Register a service provider
`boot()`	Boot all registered providers
`make(token)`	Shorthand for `container.make()`