3. Set required environment variables before running:

export PORT=3000
export NODE_ENV=development

4. Use @integration/src/http/index.ts and @integration/src/cqrs/index.ts as templates—copy them into your src/ and adjust effects/middleware lists.

5. Run your server entry point:

npx ts-node src/index.ts

Public API

httpListener

import { httpListener } from '@marblejs/http';

const listener = httpListener({
  middlewares: EffectMiddleware[],
  effects: HttpEffect[],
});

Creates an HTTP listener by composing an ordered list of middleware effects and route effects. Pass this to createServer. Middlewares run before routing; effects define route handlers.

createServer

import { createServer } from '@marblejs/http';

const server = () => createServer({
  port: number,
  listener: HttpListener,
  dependencies?: BoundDependency<any>[],
});

Bootstraps a Node.js HTTP server on the given port. Accepts optional dependency bindings for the DI context. Returns a Task-wrapped runner; call the result to start listening.

bindEagerlyTo / bindTo

import { bindEagerlyTo, bindTo } from '@marblejs/core';

bindEagerlyTo(Token)(Factory)   // resolves dependency immediately at startup
bindTo(Token)(Factory)          // resolves dependency lazily on first use

DI registration helpers. Use bindEagerlyTo for dependencies that must be initialized before any request arrives (e.g., event bus connections). Use bindTo for lazily resolved services. Pass results in the dependencies array of createServer.

messagingListener

import { messagingListener } from '@marblejs/messaging';

const eventBusListener = messagingListener({
  effects: MessagingEffect[],
});

Creates a messaging listener that processes events dispatched through the internal event bus. Compose this with EventBus and bind it via bindEagerlyTo(EventBusToken).

Working examples

Scenario - Minimal HTTP server

A single-route HTTP server with body parsing and request logging.

import * as T from 'fp-ts/lib/Task';
import { pipe } from 'fp-ts/lib/function';
import { createServer, httpListener } from '@marblejs/http';
import { r, combineRoutes } from '@marblejs/http';
import { logger$ } from '@marblejs/middleware-logger';
import { bodyParser$ } from '@marblejs/middleware-body';
import { map } from 'rxjs/operators';

const health$ = r.pipe(
  r.matchPath('/health'),
  r.matchType('GET'),
  r.useEffect(req$ => req$.pipe(
    map(() => ({ body: { status: 'ok' } })),
  )),
);

const listener = httpListener({
  middlewares: [logger$(), bodyParser$()],
  effects: [health$],
});

const server = () => createServer({ port: 3000, listener });

pipe(server, T.map(run => run()))();

Scenario - HTTP server with CQRS event bus

Wire an event bus listener alongside the HTTP server using eager dependency binding.

import * as T from 'fp-ts/lib/Task';
import { pipe } from 'fp-ts/lib/function';
import { bindEagerlyTo } from '@marblejs/core';
import { createServer, httpListener } from '@marblejs/http';
import {
  messagingListener,
  EventBusClientToken,
  EventBusClient,
  EventBusToken,
  EventBus,
} from '@marblejs/messaging';
import { logger$ } from '@marblejs/middleware-logger';
import { bodyParser$ } from '@marblejs/middleware-body';
import { myHttpEffect$ } from './effects/http.effects';
import { myEventHandler$ } from './effects/eventbus.effects';

const eventBusListener = messagingListener({
  effects: [myEventHandler$],
});

const listener = httpListener({
  middlewares: [logger$(), bodyParser$()],
  effects: [myHttpEffect$],
});

const server = () => createServer({
  port: 3000,
  listener,
  dependencies: [
    bindEagerlyTo(EventBusToken)(EventBus({ listener: eventBusListener })),
    bindEagerlyTo(EventBusClientToken)(EventBusClient),
  ],
});

pipe(server, T.map(run => run()))();

Scenario - Test-aware server bootstrap

Guard the server startup so it only runs outside test environments, a pattern used throughout the integration package.

import * as T from 'fp-ts/lib/Task';
import { pipe } from 'fp-ts/lib/function';
import { isTestEnv, getPortEnv } from '@marblejs/core/dist/+internal/utils';
import { createServer, httpListener } from '@marblejs/http';
import { logger$ } from '@marblejs/middleware-logger';
import { bodyParser$ } from '@marblejs/middleware-body';
import { api$ } from './effects/api.effects';

export const listener = httpListener({
  middlewares: [
    logger$({ silent: isTestEnv() }),
    bodyParser$(),
  ],
  effects: [api$],
});

export const server = () => createServer({
  port: getPortEnv(),
  listener,
});

export const main = !isTestEnv()
  ? pipe(server, T.map(run => run()))
  : T.of(undefined);

main();

File walkthrough

• @integration/ - Runnable integration apps demonstrating HTTP, CQRS, WebSockets, and messaging; use as copy-paste starting points.
• @integration/src/cqrs/ - Event-sourced CQRS example: event/command domain models, HTTP effects that publish commands, event bus handlers.
• @integration/src/http/ - Standard REST API example with auth middleware, CORS, body parsing, fake DAO/auth layers.
• @integration/src/messaging/ - Standalone messaging client and server entry points.
• @integration/src/websockets/ - WebSocket server wired alongside an HTTP server.
• core/ - Framework primitives: effect interfaces, context/DI container, event factory, operators, internal fp utilities.
• core/src/+internal/ - Private helpers: file reader, IxBuilder monad, observable utilities, test marble helpers, string/array/env utilities. Not part of the public API.
• http/ - createServer, httpListener, routing combinators for HTTP.
• messaging/ - messagingListener, EventBus, EventBusClient, token definitions for the internal CQRS event bus.
• middleware-body/ - bodyParser$ effect that parses JSON/urlencoded request bodies.
• middleware-cors/ - cors$ effect for Cross-Origin Resource Sharing headers.
• middleware-io/ - requestValidator$ / io helpers using io-ts schemas.
• middleware-logger/ - logger$ effect for structured request/response logging.
• middleware-multipart/ - Multipart form upload handling middleware.
• testing/ - Utilities for unit-testing effects and listeners without a real HTTP server.
• websockets/ - WebSocket listener and server factory analogous to the HTTP module.

Common pitfalls and fixes

• getPortEnv() throws at startup - Set PORT environment variable before running; getPortEnv() reads process.env.PORT and throws if absent.
• isTestEnv() silences server startup - This checks NODE_ENV === 'test'; ensure NODE_ENV is not set to test in production or staging.
• bindEagerlyTo vs bindTo ordering - Dependencies bound with bindEagerlyTo must be listed before any lazy bindTo bindings that depend on them; wrong order causes unresolved context tokens.
• RxJS version mismatch - Marble.js requires RxJS 7.x; mixing RxJS 6.x from other packages causes Observable instanceof checks to fail silently. Pin "rxjs": "^7.0.0" in your root package.json.
• fp-ts pipe import path - Import pipe from fp-ts/lib/function, not fp-ts/pipeable (deprecated in fp-ts 2.x); using the wrong path causes runtime undefined errors.
• ESM/CJS interop with fp-ts - If bundling with esbuild or Webpack, set esModuleInterop: true in tsconfig.json and ensure your bundler resolves fp-ts/lib/* CommonJS paths correctly.

Vibe-coding prompt template

I have purchased the Marble.js source block (marblejs@4.0.0). The source is in
`./source/` and the integration guide is in `USAGE.md`. Please help me integrate
Marble.js into my existing Node.js/TypeScript project step by step.

Context:
- Source root: ./source/ (packages: core, http, messaging, websockets, middleware-*, testing, @integration)
- Integration guide: USAGE.md (read it first for real exports and snippets)
- Upstream package: user@example.com / @marblejs/* scoped packages
- My project currently has: [describe your existing server setup, e.g. plain Express, existing tsconfig, etc.]

Tasks:
1. Install all required npm dependencies listed in USAGE.md.
2. Update tsconfig.json with the paths aliases shown in USAGE.md if I want to
   use local source instead of npm.
3. Create a src/index.ts HTTP server using httpListener and createServer,
   with logger$ and bodyParser$ middleware, and at least one GET route.
4. If I need an event bus, add the CQRS setup from USAGE.md scenario 2.
5. Wire environment variables PORT and NODE_ENV correctly.
6. Show me how to run the server with ts-node.

Only use symbols and imports that appear in USAGE.md or the source files.
Do not invent API methods. If something is unclear, ask before generating code.

License and credit

Marble.js is MIT licensed. See source/README.md or the upstream repository for the full license text. Upstream package: @marblejs/core on npm. Source repository and documentation: marblejs.gitbook.io.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Seneca Node.js Microservice Toolkit for Backends

Automation, Utilities & Developer Tools

無料