lumen-framework 3.0.0

package/LICENSE

@@ -0,0 +1,26 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Postlight
+Copyright (c) 2019-2026 Nick Schot and contributors
+
+Lumen is a fork of Lux (https://github.com/postlight/lux). The copyright notice
+above is retained for the original work, as the MIT License requires; the second
+line covers the changes made in this fork.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# Lumen
+
+[![CI](https://github.com/nickschot/lux/actions/workflows/ci.yml/badge.svg)](https://github.com/nickschot/lux/actions/workflows/ci.yml) [![npm](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.
+
+\* _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."
+
+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:
+
+```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);
+    });
+});
+```
+
+Could you imagine how ugly that gets when you have to implement pagination, filtering, sorting, or—better yet—formatting the response for JSON API?
+
+Also, where does that code live? In what file and folder would I find it? What pattern do you use for organizing this code?
+
+😲 Ok ok give me back Rails I'll worry about performance and scaling later. After all, premature optimization is the root of all evil.
+
+##### Problem.resolve();
+
+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?
+
+Fortunately ES2015+ has introduced great new features to the JavaScript language, especially when it comes to meta programming.
+
+With Lumen your code from before can now look like this:
+
+```javascript
+class PostsController extends Controller {
+  index(req, res) {
+    return Post.all();
+  }
+}
+```
+
+Except CRUD actions are taken care of automatically so it would actually look like this:
+
+```javascript
+class PostsController extends Controller {
+
+}
+```
+
+It's about time a Node server framework learned something from client-side JS frameworks.
+
+
+## How?
+
+### Installation
+
+```bash
+npm install -g lumen-framework
+```
+
+### Creating Your First Project
+
+Use the `new` command to create your first project.
+
+```bash
+lumen new <app-name>
+```
+
+### Running
+
+To run your application use the `serve` command.
+
+```bash
+cd <app-name>
+lumen serve
+```
+
+## Useful Links
+
+*   [JSON API](http://jsonapi.org/)
+*   [Knex.js](http://knexjs.org/)
+*   [Vitest](https://vitest.dev/)
+
+## Attribution
+
+Lumen is a fork of [**Lux**](https://github.com/postlight/lux), created by
+[Zachary Golba](https://github.com/zacharygolba) and originally developed and maintained by
+[Postlight](https://postlight.com/). Essentially all of the framework's design — the
+convention-over-configuration approach, the automatic CRUD controllers, the JSON:API
+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
+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
+original copyright notice is retained in [LICENSE](./LICENSE) alongside that of this
+fork's contributors.
+
+*   Original repository: [postlight/lux](https://github.com/postlight/lux)
+*   Original announcement: [Not Another Node.js Framework](https://trackchanges.postlight.com/not-another-node-js-framework-33103ebeedf8)

package/bin/lumen

@@ -0,0 +1,275 @@
+#!/usr/bin/env -S node --enable-source-maps
+
+'use strict';
+
+// `--enable-source-maps` (above) replaces the `source-map-support` shim the app
+// compiler used to inject into every bundle: the flag applies process-wide, so
+// 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');
+
+const { version: VERSION } = require('../package.json');
+
+function inLumenProject() {
+  const cwd = process.cwd();
+
+  try {
+    const { dependencies } = require(path.join(cwd, 'package.json'));
+
+    if (dependencies && dependencies['lumen-framework']) {
+      return true;
+    }
+  } catch (err) {
+    // No readable package.json here — fall through to the layout check below.
+  }
+
+  // Fall back to detecting the application layout the compiler requires.
+  //
+  // This used to match a hardcoded `lumen/test/test-app` path fragment, which
+  // existed because the framework's own fixture app does not depend on the
+  // framework. That broke the moment the project was renamed (the checkout is
+  // still `lux/`), taking the whole suite with it — and it would break again
+  // for anyone whose directory happens to be named differently. Checking for
+  // the app's shape is both rename-proof and closer to the real question.
+  return (
+    existsSync(path.join(cwd, 'app', 'index.js'))
+    && existsSync(path.join(cwd, 'config', 'database.js'))
+  );
+}
+
+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);
+  } else if (!Reflect.has(process.env, key)) {
+    Reflect.set(process.env, key, def);
+  }
+}
+
+function exec(cmd, ...args) {
+  const handler = require('../dist/cli.cjs')[cmd];
+  const needsProject = new RegExp(
+    '^(?:db:.+|test|build|serve|console|generate|destroy)$'
+  );
+
+  if (needsProject.test(cmd) && !inLumenProject()) {
+    return Promise.reject(
+      new Error('Directory does not contain a valid Lumen application.')
+    );
+  }
+
+  return handler(...args);
+}
+
+function exit(code) {
+  process.exit(typeof code === 'number' ? code : 0);
+}
+
+function rescue(err) {
+  console.error(err.stack);
+  exit(1);
+}
+
+cli.version(VERSION);
+
+cli
+  .command('n <name>')
+  .alias('new')
+  .description('Create a new application')
+  .option(
+    '--database [database]',
+    'Database driver',
+    /^(postgres|sqlite|mysql)$/i,
+    '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')
+  .description('Build your application')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ useWeak }) => {
+    exec('build', !useWeak).then(exit).catch(rescue);
+  });
+
+cli
+  .command('c')
+  .alias('console')
+  .description('Load your application into a repl')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    setEnvVar('NODE_ENV', environment, 'development');
+    process.env.LUMEN_CONSOLE = true;
+
+    exec('build', !useWeak)
+      .then(() => exec('repl'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli
+  .command('s')
+  .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 =>
+    Number.parseInt(port, 10)
+  )
+  .option('-H, --hot', 'Reload when a file change is detected')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ hot, port, cluster, environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('PORT', port, 4000);
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('serve', { hot, cluster, useStrict }))
+      .catch(rescue);
+  });
+
+cli
+  .command('g <type> <name> [attrs...]')
+  .alias('generate')
+  .description(
+    'Example: lumen generate model user name:string email:string admin:boolean'
+  )
+  .action((type, name, attrs) => {
+    exec('generate', { type, name, attrs }).then(exit).catch(rescue);
+  });
+
+cli
+  .command('d')
+  .alias('destroy <type> <name>')
+  .description('Example: lumen destroy model user')
+  .action((type, name) => {
+    exec('destroy', { type, name }).then(exit).catch(rescue);
+  });
+
+cli
+  .command('db:create')
+  .description('Create your database schema')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('dbcreate'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli
+  .command('db:drop')
+  .description('Drop your database schema')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('dbdrop'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli
+  .command('db:reset')
+  .description('Drop your database schema and create a new schema')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('dbdrop'))
+      .then(() => exec('dbcreate'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli
+  .command('db:migrate')
+  .description('Run database migrations')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('dbmigrate'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli
+  .command('db:rollback')
+  .description('Rollback the last database migration')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('dbrollback'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli
+  .command('db:seed')
+  .description('Add fixtures to your db from the seed function')
+  .option('-e, --environment [env]', '(Default: development)')
+  .option('-w, --use-weak', 'Use weak mode')
+  .action(({ environment, useWeak }) => {
+    const useStrict = !useWeak;
+
+    setEnvVar('NODE_ENV', environment, 'development');
+
+    exec('build', useStrict)
+      .then(() => exec('dbseed'))
+      .then(exit)
+      .catch(rescue);
+  });
+
+cli.on('*', commandNotFound).parse(process.argv);
+
+if (!cli.args.length) {
+  cli.help();
+}