Foundations

The three forms

Nearly everything in Stone.js, handlers, services, middleware, listeners, can be written in three shapes: a class, a factory, or a plain function. The three are interchangeable, with one deliberate rule about the container that follows from what each shape is.

#Class, factory, function

The principle

Teams and tasks differ: some reach for classes and structure, some for functions and composition. A framework that supports only one imposes a style. Supporting all three, equivalently, lets the code match the problem instead of the framework.

In Stone.js

The class form is instantiated and receives its bindings in the constructor. The factory is a function that receives the container and returns the working object. The function is the bare logic, and it receives no container.

app/forms.tsts

// Class: bindings arrive in the constructor.
@Service({ alias: 'tasks' })
class TaskService { constructor ({ config }) { /* ... */ } }

// Factory: receives the container, returns the object.
const TaskService = ({ config }) => ({ list: () => [/* ... */] })

// Function: bare logic, no container. Great for pure handlers.
const ping = (event) => ({ pong: event.get('n', 1) })

#The one rule

The function form never receives the container. If you need dependencies, use a class or a factory.

This is not an arbitrary limit; it is the definition. A plain function that took the container would just be a factory. So the function form is precisely the shape for logic that needs nothing injected, and it stays the simplest thing that can possibly work.

#Where the rule bites

Providers always need the container, to register into it, so they forbid the function form: a provider is a class or a factory, never a plain function. Everywhere else, pick the form that fits, and switch freely as a piece of code grows from a pure function into something that needs a dependency.