lumen-framework 3.1.1 → 4.0.0

package/README.md

@@ -2,145 +2,111 @@
 
 [![CI](https://github.com/nickschot/lux/actions/workflows/ci.yml/badge.svg)](https://github.com/nickschot/lux/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/lumen-framework.svg?style=flat-square)](https://www.npmjs.com/package/lumen-framework)
 
-A MVC style framework for building highly performant, large scale JSON APIs that anybody who knows the JavaScript language and its modern features will understand.
+An MVC-style Node.js framework for building [JSON:API 1.0](https://jsonapi.org/)
+compliant REST APIs with very little code. Controllers get create, read, update
+and delete for free — including pagination, sorting, filtering, sparse
+fieldsets and compound documents — and the ORM sits on top of
+[Knex](https://knexjs.org/).
 
-\* _Inspired by [Rails](https://github.com/rails/rails/), [Ember](http://emberjs.com/), and [React](https://facebook.github.io/react/)._
-
-**Disclaimer:**
-
-This isn't another wrapper around [Express](http://expressjs.com/) or a framework for building frameworks. This also isn't a replacement for server-side frameworks that render DHTML.
-
-[Check out the Medium Article!](https://trackchanges.postlight.com/not-another-node-js-framework-33103ebeedf8)
-
-## What?
-
-### Features
-
-*   Automatic CRUD actions in controllers
-*   Automatic pagination, sorting, filtering via query params in controllers
-*   CLI for eliminating boiler plate
-*   [JSON API](http://jsonapi.org/) 1.0 compliant out of the box
-*   Optimized database queries based on serialized attributes and associations
-*   Highly extensible - just write reusable JavaScript functions
-*   Pairs nicely with client-side JavaScript applications 🍷
-*   Easy to contribute
-*   Routes are stored and accessed via a `Map` not an `Array`
-*   Embraces ES2015 and beyond
-    *   Classes
-    *   Modules
-    *   Promises & async/await
-    *   Arrow Functions
-    *   etc.
-
-
-### Philosophies
-
-##### Minimal API surface area
-
-Lumen uses JavaScript's standard library rather than creating a ton of functions you'll have to learn and remember.
-
-After your learn how to use it, you'll rarely need to look at the docs.
-
-##### Pure functions are awesome
-
-Or more appropriately somewhat pure functions are awesome.
-
-Serving content is done by returning objects, arrays, or other primitives rather than calling `res.end(/* content */);` and returning nothing.
-
-##### Convention over configuration
-
-[Rails](http://rubyonrails.org/) and [Ember](http://emberjs.com/) are great because they make hard decisions for you and make it possible to submit a PR on your first day at a new company. This is rare with Node server frameworks.
-
-
-## Why?
-
-Frameworks like Rails are pretty great. You can build amazing applications in a reasonable amount of time without a ton of developers working on a project. They have their limitations though. They can be slow and sometimes hard to scale. Not to mention WebSocket support being so-so.
-
-##### Node to the rescue.
-
-It's fast, it allows the developer to get low level with a relatively simple API, WebSockets are stable and supported out of the box, and last but not least it's just JavaScript.
-
-##### Not so fast (metaphorically speaking).
-
-The last bit there "It's just JavaScript" has actually been somewhat of a double-edged sword. This has positioned Node as a "great prototyping tool" or "only used for micro services."
+```javascript
+import { Controller } from 'lumen-framework';
 
-I can somewhat see why people would think that when returning a list of the first 10 records from a SQL database table looks like this:
+class PostsController extends Controller {
+  params = ['title', 'body'];
+}
 
-```javascript
-app.get('/posts', (req, res) => {
-  Post.findAll()
-    .then(posts => {
-      res.status(200).json(posts);
-    }, err => {
-      console.error(err);
-      res.status(500).send(err.message);
-    });
-});
+export default PostsController;
 ```
 
-Could you imagine how ugly that gets when you have to implement pagination, filtering, sorting, or—better yet—formatting the response for JSON API?
+That controller, a model and a serializer are a complete `/posts` resource:
+`GET /posts?sort=-title&page[size]=10&fields[posts]=title`, `GET /posts/1`,
+`POST`, `PATCH` and `DELETE` all work.
 
-Also, where does that code live? In what file and folder would I find it? What pattern do you use for organizing this code?
+## Features
 
-😲 Ok ok give me back Rails I'll worry about performance and scaling later. After all, premature optimization is the root of all evil.
+- Automatic CRUD actions in controllers, overridable one at a time
+- Pagination, sorting and filtering from query params, limited to the fields
+  you allow
+- JSON:API compound documents (`?include=`), sparse fieldsets, relationship
+  and related endpoints
+- Visibility rules declared once per namespace and applied to every query a
+  request makes — listings, lookups, relationships and includes
+- Database queries shaped by what the serializer actually outputs
+- Structured request logging (JSON or plain text) with credential filtering
+- A CLI that generates models, controllers, serializers, migrations and whole
+  resources
+- Written in TypeScript; type declarations ship with the package
+- SQLite, PostgreSQL and MySQL via Knex
 
-##### Problem.resolve();
+## Requirements
 
-Shouldn't there be a better way to do this? Can't I just return a promise or a JavaScript primitive instead of basically using the native Node http server API?
+- Node.js **22.14** or later
+- One of `better-sqlite3`, `pg` or `mysql2` (`lumen new` adds the one you pick)
 
-Fortunately ES2015+ has introduced great new features to the JavaScript language, especially when it comes to meta programming.
+## Getting started
 
-With Lumen your code from before can now look like this:
-
-```javascript
-class PostsController extends Controller {
-  index(req, res) {
-    return Post.all();
-  }
-}
+```bash
+npm install -g lumen-framework
 ```
 
-Except CRUD actions are taken care of automatically so it would actually look like this:
-
-```javascript
-class PostsController extends Controller {
-
-}
+```bash
+lumen new blog
 ```
 
-It's about time a Node server framework learned something from client-side JS frameworks.
-
-
-## How?
+```bash
+cd blog
+```
 
-### Installation
+```bash
+lumen generate resource post title:string body:text
+```
 
 ```bash
-npm install -g lumen-framework
+lumen db:migrate
 ```
 
-### Creating Your First Project
+```bash
+lumen serve
+```
 
-Use the `new` command to create your first project.
+The API is now on `http://localhost:4000`:
 
 ```bash
-lumen new <app-name>
+curl -X POST localhost:4000/posts -H 'Content-Type: application/vnd.api+json' -d '{"data":{"type":"posts","attributes":{"title":"Hello","body":"First post"}}}'
 ```
 
-### Running
+`lumen new --database postgres` (or `mysql`) starts a project on another
+database; `lumen --help` and `lumen <command> --help` list every command and
+option. The [getting-started guide](docs/guides/getting-started.md) walks
+through this step by step, with related resources and the requests the API
+answers.
+
+## Documentation
+
+- [Guides](docs/guides/) — start with
+  [Getting started](docs/guides/getting-started.md).
+- [UPGRADING.md](UPGRADING.md) — what an app has to change, or check, to
+  move to Lumen 4.0.
+- [CHANGELOG.md](CHANGELOG.md) — release notes.
+- [examples/social-network](examples/social-network/) — an example app that
+  uses most of the framework, with a map of where each feature lives.
+- API reference — every exported class and type, generated from the source:
+  `pnpm docs:api` in a checkout of this repository, then open
+  `docs/api/index.html`.
 
-To run your application use the `serve` command.
+## Contributing
 
 ```bash
-cd <app-name>
-lumen serve
+pnpm install
 ```
 
-## Useful Links
+```bash
+pnpm build && pnpm test
+```
 
-*   [JSON API](http://jsonapi.org/)
-*   [Knex.js](http://knexjs.org/)
-*   [Vitest](https://vitest.dev/)
+The test suite needs the fixture app's dependencies
+(`pnpm --dir test/test-app install`) and builds a SQLite database on first
+run. [RELEASE.md](RELEASE.md) describes how releases are cut.
 
 ## Attribution
 
@@ -153,7 +119,7 @@ serialization, the ORM built on Knex — is their work.
 Upstream development stopped after `v1.2.3` (2018). This fork picks it up from there: it
 was renamed to Lumen to avoid confusion with the original, since it is no longer a
 drop-in continuation of it — the toolchain has been modernized (TypeScript, esbuild,
-Vitest, Node 20+) and the public API has been allowed to change. Lumen is **not** an
+Vitest, Node 22+) and the public API has been allowed to change. Lumen is **not** an
 official Postlight project, and the Postlight team provides no support for it.
 
 The original is MIT licensed, and Lumen remains MIT licensed under the same terms. The

package/bin/lumen

@@ -7,12 +7,12 @@
 // the required app bundle and the cluster workers (which inherit execArgv) both
 // map stack traces back to source.
 
-const { EOL } = require('os');
 const path = require('path');
 const { existsSync } = require('fs');
 
-const cli = require('commander');
-const { red, green } = require('chalk');
+// commander is ESM-only from v15 on; `require()` of it needs Node >= 22.12
+// (unflagged require(esm)), within the engines floor.
+const { program: cli, Option } = require('commander');
 
 const { version: VERSION } = require('../package.json');
 
@@ -25,7 +25,7 @@ function inLumenProject() {
     if (dependencies && dependencies['lumen-framework']) {
       return true;
     }
-  } catch (err) {
+  } catch {
     // No readable package.json here — fall through to the layout check below.
   }
 
@@ -43,13 +43,6 @@ function inLumenProject() {
   );
 }
 
-function commandNotFound(cmd) {
-  console.log(
-    `${EOL}  ${red(cmd)} is not a valid command.${EOL.repeat(2)}`,
-    ` Use ${green('lumen --help')} for a full list of commands.${EOL}`
-  );
-}
-
 function setEnvVar(key, val, def) {
   if (val) {
     Reflect.set(process.env, key, val);
@@ -61,7 +54,7 @@ function setEnvVar(key, val, def) {
 function exec(cmd, ...args) {
   const handler = require('../dist/cli.cjs')[cmd];
   const needsProject = new RegExp(
-    '^(?:db:.+|test|build|serve|console|generate|destroy)$'
+    '^(?:db:.+|build|serve|console|generate|destroy)$'
   );
 
   if (needsProject.test(cmd) && !inLumenProject()) {
@@ -88,24 +81,15 @@ cli
   .command('n <name>')
   .alias('new')
   .description('Create a new application')
-  .option(
-    '--database [database]',
-    'Database driver',
-    /^(postgres|sqlite|mysql)$/i,
-    'sqlite'
+  .addOption(
+    new Option('--database <database>', 'Database driver')
+      .choices(['postgres', 'sqlite', 'mysql'])
+      .default('sqlite')
   )
   .action((name, { database }) => {
     exec('create', name, database).then(exit).catch(rescue);
   });
 
-cli
-  .command('t')
-  .alias('test')
-  .description("Run your application's test suite")
-  .action(() => {
-    exec('test').then(exit).catch(rescue);
-  });
-
 cli
   .command('b')
   .alias('build')
@@ -119,7 +103,7 @@ cli
   .command('c')
   .alias('console')
   .description('Load your application into a repl')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     setEnvVar('NODE_ENV', environment, 'development');
@@ -136,8 +120,8 @@ cli
   .alias('serve')
   .description('Serve your application')
   .option('-c, --cluster', 'Run in cluster mode')
-  .option('-e, --environment [env]', '(Default: development)')
-  .option('-p, --port [port]', '(Default: 4000)', port =>
+  .option('-e, --environment <env>', '(Default: development)')
+  .option('-p, --port <port>', '(Default: 4000)', port =>
     Number.parseInt(port, 10)
   )
   .option('-H, --hot', 'Reload when a file change is detected')
@@ -164,8 +148,8 @@ cli
   });
 
 cli
-  .command('d')
-  .alias('destroy <type> <name>')
+  .command('d <type> <name>')
+  .alias('destroy')
   .description('Example: lumen destroy model user')
   .action((type, name) => {
     exec('destroy', { type, name }).then(exit).catch(rescue);
@@ -174,7 +158,7 @@ cli
 cli
   .command('db:create')
   .description('Create your database schema')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     const useStrict = !useWeak;
@@ -190,7 +174,7 @@ cli
 cli
   .command('db:drop')
   .description('Drop your database schema')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     const useStrict = !useWeak;
@@ -206,7 +190,7 @@ cli
 cli
   .command('db:reset')
   .description('Drop your database schema and create a new schema')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     const useStrict = !useWeak;
@@ -223,7 +207,7 @@ cli
 cli
   .command('db:migrate')
   .description('Run database migrations')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     const useStrict = !useWeak;
@@ -239,7 +223,7 @@ cli
 cli
   .command('db:rollback')
   .description('Rollback the last database migration')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     const useStrict = !useWeak;
@@ -255,7 +239,7 @@ cli
 cli
   .command('db:seed')
   .description('Add fixtures to your db from the seed function')
-  .option('-e, --environment [env]', '(Default: development)')
+  .option('-e, --environment <env>', '(Default: development)')
   .option('-w, --use-weak', 'Use weak mode')
   .action(({ environment, useWeak }) => {
     const useStrict = !useWeak;
@@ -268,8 +252,6 @@ cli
       .catch(rescue);
   });
 
-cli.on('*', commandNotFound).parse(process.argv);
-
-if (!cli.args.length) {
-  cli.help();
-}
+// An unknown command errors (with a "did you mean" suggestion) and no command
+// prints the help — both built into commander, exiting 1.
+cli.parse(process.argv);