S42-Core

Español · Documentation · Website

S42-Core 3.0.11 is a Bun-first TypeScript backend framework for HTTP APIs, module-oriented services, distributed domain events, and common persistence workloads.

It is developed by Cesar Casas and Stock42 LLC with AI-assisted engineering workflows.

Requirements

• Bun >=1.3.0
• TypeScript/ESM projects
• Redis/Valkey, MongoDB, PostgreSQL, MySQL, SQLite, or SQS only when the corresponding component is used

Install the public package:

bun add s42-core

What It Provides

• HTTP bootstrap over Bun.serve with native route maps and a fallback matcher.
• Convention-based module discovery with Bun.Glob.
• Three module types: mws, share, and full.
• Controller-level middleware selection.
• Distributed events through Redis or SQS adapters.
• MongoDB, Redis/Valkey, multi-engine SQL, and direct SQLite helpers.
• SSE, worker clustering, runtime statistics, dependency injection, and leveled logging.

Quick Start

import { Modules, RouteControllers, Server } from 's42-core'

const modules = new Modules('./modules')
await modules.load()

const server = new Server()
await server.start({
	port: 5678,
	RouteControllers: new RouteControllers(modules.getControllers()),
	hooks: modules.getHooks(),
})

console.info(server.getURL())

The repository includes a module demo entrypoint:

bun run modules/server.ts

In the current checkout, that demo and bun run typecheck:modules stop on a known fixture issue: modules/operators/controllers/operatorList.ts imports the missing ../events/emit file. The package bootstrap above is unaffected.

Module Model

S42-Core discovers **/__module__.ts files and loads enabled modules in this order:

1. mws: on-demand request middleware from mws/index.ts.
2. share: reusable code and contracts; no automatic controller/event loading.
3. full: controllers and optional events.

Minimal manifest:

export default {
	name: 'operators',
	version: '1.0.0',
	type: 'full',
	enabled: true,
	initialize: async () => {
		// Runs after this module has loaded.
	},
}

Typical layout:

modules/
  auth/
    __module__.ts
    mws/index.ts
  share/
    __module__.ts
    services/
    types/
  operators/
    __module__.ts
    controllers/
    events/

dependencies in a manifest is metadata; the current loader does not resolve or enforce dependency versions. See MODULES for the complete runtime contract.

Public Package API

Only exports from src/index.ts are supported package imports.

| Area | Public exports | | --------------- | --------------------------------------------------------------------------------------- | | HTTP | Server, RouteControllers, Controller, Res, getControllersStats | | Modules | Modules, Module, Model, Service, Controllers, getModulesStats | | Events | EventsDomain, RedisEventsAdapter, SQSEventsAdapter | | Data | MongoClient, RedisClient, SQL, SQLite, SQLError, isSQLError, Dependencies | | Runtime | Cluster, SSE, CoreStats | | Logging/testing | logger, setLogLevel, getLogLevel, setLogSink, Test |

The package also exports the TypeScript types declared by the root entrypoint, including module, event, SQL, logger, SSE, CoreStats, and statistics contracts.

MongoDBStorage, sendEmail (src/Mailgun), and ViewTemplates exist in the repository but are internal utilities. They are not exported by the package, and imports such as s42-core/dist/... are unsupported.

Documentation

Start with the consolidated, source-aligned guide:

• Master documentation (English)

Component references:

• Runtime: SERVER, ROUTECONTROLLERS, CONTROLLER, RESPONSE, MODULES, and CLUSTER
• Events: EVENTSDOMAIN
• Data: REDISDB, MONGODB, SQL, and SQLITE
• Utilities: SSE, CORESTATS, DEPENDENCIES, LOGGER, and TEST
• Internal reference only: MAILGUN and VIEWTEMPLATE

Spanish component references use the .es.md suffix, beginning with SERVER.es and MODULES.es.

Operational Notes

• CoreStats is disabled by default. When enabled, it exposes host and process information and does not add authentication; protect the route before using it outside a trusted network.
• RouteControllers currently emits permissive, fixed CORS headers. Review the routing security notes before production exposure.
• SSE requires the raw Web Request; the normalized controller request does not currently preserve its abort signal.
• MongoDB, Redis, and EventsDomain use process-wide singletons: the first configuration passed to getInstance() wins.

Development

bun run typecheck
bun run typecheck:modules
bun run lint
bun test

All gates except typecheck:modules pass in the current checkout; its known fixture failure is described above.

See CHANGELOG.md for shipped changes and ROADMAP.md for planned features.

License

MIT