Foundations

The two paradigms

Stone.js supports two ways to write everything, declarative decorators and imperative define* helpers, and holds them at strict parity. Neither is a second-class citizen; neither can do something the other cannot. You choose the one that fits how you think.

#Two syntaxes, one manifest

The principle

A framework that favours one authoring style forces a whole team into it. If two styles compile to the exact same internal representation, the choice becomes ergonomic rather than architectural, and no capability is lost either way.

In Stone.js

A decorator writes stone.* keys by introspection; a define*meta-module writes the same keys explicitly. Both feed the one Blueprint. Downstream, the kernel cannot tell which you used, because there is nothing left to tell apart.

app/Tasks.tsdeclarativeimperative

import { Service } from '@stone-js/core'
import { Get, EventHandler } from '@stone-js/router'

@Service({ alias: 'tasks' })
export class TaskService {
  list () { return [/* ... */] }
}

@EventHandler('/tasks')
export class TaskController {
  constructor ({ tasks }) { this.tasks = tasks }

  @Get('/')
  list () { return this.tasks.list() }
}
import { defineService } from '@stone-js/core'
import { defineEventHandler, defineRoutes } from '@stone-js/router'

const TaskService = () => ({ list: () => [/* ... */] })

const TaskController = ({ tasks }) => ({ list: () => tasks.list() })

export const services = [defineService(TaskService, { alias: 'tasks' }, true)]
export const routes = defineRoutes([
  [defineEventHandler(TaskController, 'list'), { path: '/tasks', method: 'GET' }]
])

Decorators or define*. Superposed, until you choose. The Blueprint they produce is identical.

#When each shines

Declarative: classes, annotations, introspection. Reads well when the shape of the app is static and you like structure near the code it configures.
Imperative: plain values and define* calls. Shines for dynamic construction, conditional wiring, and factory-heavy or functional codebases.

The switch at the top of this site is the same idea applied to the docs: pick a paradigm and every example follows you. Nothing about the framework changes; only the pen does.