Skip to main content

Layer

Layers are named groups of handlers that organise code by functional concern within a realm. For the conceptual overview and the list of well-known layer names, see concepts/layer.

Folder Structure​

Well-known layer folders are auto-discovered — no layer.server.ts is needed:

realmname/
├── server.ts # Optional — only for realm-level shared config
├── error/ # Auto-activated (server, integration)
│ └── error.ts
├── adapter/ # Auto-activated (server, integration)
│ ├── db.ts # Self-contained adapter with config + validation
│ └── db/ # Handler group: realmname.db
│ ├── userUserAdd.ts
│ └── userUserFind.ts
├── orchestrator/ # Auto-activated (server, integration)
│ ├── dispatch.ts # Self-contained orchestrator with config + validation
│ └── user/ # Handler group: realmname.user
│ ├── ~.schema.ts # Auto-generated validation schema
│ └── userUserAdd.ts
├── gateway/ # Auto-activated (server, integration)
│ └── api/
│ └── user.yaml
├── sim/ # Auto-activated (server, integration)
│ └── backend.ts
├── server/ # Server-only well-known sub-layers
│ ├── api/ # Auto-activated (server, integration)
│ ├── init/ # Auto-activated (server, default)
│ └── test/ # Server tap tests (server, integration)
│ └── test/
│ └── testUser.ts
└── test/ # BROWSER layer (Playwright *.play.ts) — auto-activated (browser, integration)
└── user.play.ts

Custom layer folders (non-well-known names) require a layer.server.ts or layer.browser.ts:

// myCustomLayer/layer.server.ts
import {layer} from '@feasibleone/blong';

export default layer({
default: true, // active in all environments
microservice: true, // additionally active in microservice deployment
});

Self-Contained Layer Pattern​

Each layer owns its configuration and validation. Avoid putting layer config in the parent server.ts — this makes the layer reusable and reduces the number of files to change when adding a new adapter or orchestrator.

Adapter​

// adapter/db.ts
import {adapter} from '@feasibleone/blong';

export default adapter(blong => ({
extends: 'adapter.knex',

validation: blong.type.Object({
namespace: blong.type.Union([blong.type.String(), blong.type.Array(blong.type.String())]),
imports: blong.type.Union([blong.type.String(), blong.type.Array(blong.type.String())]),
logLevel: blong.type.Optional(blong.type.String()),
}),

activation: {
default: {
namespace: 'db/$subject',
imports: '$subject.db',
},
dev: {logLevel: 'trace'},
prod: {logLevel: 'warn'},
},
}));

Orchestrator​

// orchestrator/dispatch.ts
import {orchestrator} from '@feasibleone/blong';

export default orchestrator(blong => ({
extends: 'orchestrator.dispatch',

validation: blong.type.Object({
namespace: blong.type.Union([blong.type.String(), blong.type.Array(blong.type.String())]),
imports: blong.type.Union([
blong.type.String(),
blong.type.Array(blong.type.String()),
blong.type.Array(blong.type.RegExp()),
]),
destination: blong.type.Optional(blong.type.String()),
}),

activation: {
default: {
destination: 'db',
namespace: ['$subject'],
imports: [/^$subject\./],
},
},
}));

Realm Entry Point (only when needed)​

server.ts is optional. Include it only when config or validation must be shared across layers:

// server.ts
import {realm} from '@feasibleone/blong';

export default realm(blong => ({
url: import.meta.url,
validation: blong.type.Object({
myService: blong.type.Object({url: blong.type.String()}),
}),
activation: {
default: {
myService: {url: 'http://localhost:8080'},
},
},
}));

Configuration Levels​

Configuration sits next to the thing it configures, and the levels override each other in a fixed order — the last one that sets a value wins:

LevelWhereScope
Component configactivation in the layer file (or its validation)one adapter/orchestrator
Handler group defaultsconfig.ts in the group folderone realmname.foldername
Realm overrideconfig.namespace.<group> in the realm's server.tsone group, for one deployment

A component's own config is merged as default → each active intent → the platform's configs → ci when the process runs on CI, so a dev: block overrides a default: one and a prod: block overrides neither unless prod is active. See the configuration pattern for the global merge chain that decides the effective values, and concepts/layer for why the config belongs in the layer.

Group-Level Default Config​

Each handler group folder can contain a config.ts that sets defaults for all handlers in that group:

// orchestrator/payment/config.ts
export default {
default: {
timeout: 30000,
endpoint: 'https://api.payment.example.com',
},
dev: {
endpoint: 'https://api.dev.payment.example.com',
},
};

The blocks are merged in the order default, then the active intents, so a handler in that folder reads the effective object as its config. A realm can override one value for a deployment without touching the folder — the realm's namespace.<folder> entry is merged on top:

// server.ts — the override wins over the group's own config.ts
export default realm(blong => ({
url: import.meta.url,
config: {
prod: {
namespace: {
payment: {endpoint: 'https://payment.internal'},
},
},
},
}));

Portability​

Because each layer declares when it is active, the same realm runs as a monolith and as separate services without edits: a layer whose activation also names microservice is loaded when the realm is deployed on its own, and the realm's server.ts never had to know which case it was in.

Handler Group Naming​

Groups are named realmname.foldername. For example, a realm named user with a folder orchestrator/user/ produces the group name user.user.

Reference groups in the imports property:

activation: {
default: {
namespace: ['user', 'role'],
imports: ['user.user', 'user.role'],
},
},

Error Layer​

// realmname/error/error.ts
export default {
userNotFound: 'User not found',
userExists: 'User already exists',
permissionDenied: 'Permission denied',
};

One Handler Per File​

Each handler lives in its own file named after the semantic triple:

  • userUserAdd → userUserAdd.ts
  • paymentTransferSend → paymentTransferSend.ts

This makes ctrl+p / quick-open discovery fast: typing uua immediately finds userUserAdd.ts.

Best Practices​

  1. Co-locate config — put validation and activation inside the layer file, not server.ts.
  2. One file per handler — keeps diffs small and discovery fast.
  3. Group by entity — place handlers for the same business entity in the same folder.
  4. Use ~.schema.ts for auto-generated validation (see validation).
  5. Error first — define errors in the error layer before implementing any business logic.

Examples​

  • Complete realm: test/framework/demo/
  • EIP patterns with mocks: demo/blong-eip/