citizen - npm Package Versions

1.0.0

New features:

• ES module support
• Route controllers and actions have their own config that extends the global config

Enhancements/fixes:

• citizen checks for the NODE_ENV environment variable and sets its mode accordingly
  • If NODE_ENV is undefined, citizen defaults to production mode
  • Setting the mode manually in your citizen configuration overrides NODE_ENV
• Hot module replacement now works with the app cache enabled
  • Caching is now enabled by default to maintain consistency between development and production environments, but can still be disabled manually via the config for debugging purposes
• Log files are split into access.log, error.log, and debug.log and can be enabled independently
  • If running only a single citizen app server instance, access logs will likely affect performance
  • Debug logs mimic development mode console logs, thus are extremely verbose and peformance-intensive
  • Client (400) and server (500) error logs can be enabled/disabled independently
• citizen now uses the HTTP Accept header to determine the response format
  • Supported response types are text/html, text/plain, application/json, and application/javascript (JSON-P)
• app.log() will attempt to create the logs directory if it doesn't already exist
• Handling of 500 errors can be configured
  • capture (default) will write the error to the log, render an error view to the client, and keep the process/server running
  • exit will send a 500 to the client without rendering a view, write the error to the log, throw the error, then exit the process
• The previously required x-citizen-uri header for routing behind proxy servers is deprecated in favor of industry standard Forwarded headers
  • X-Forwarded header support has been deprecated and will be removed from future versions
• Previously reserved URL parameters (type, ajax, show, and task) have been released for dev use
• JSON requests now provide the local context of the entire controller chain and all includes in the response
• app.cache.set() now automatically expires/clears the specified cache key if it already exists and creates a new cache item rather than throwing an error
• The file watcher, which relies upon chokidar, now accepts all settings available in chokidar via a new options configuration
  • Please reference the chokidar documentation for available options if your environment requires customizations (usePolling for networked file systems, for example)
• The next directive (previously handoff) now accepts a route pathname similar to the include route pathname, which allows simulating a different route when handing off to the next controller in the chain
• Views no longer require subfolders
  • Old pattern (still supported): views for a given route controller go within a folder matching that controller name, with the default view also matching the controller name
  • New pattern: views can reside within the main views folder directly, with the default view for a controller matching the controller name, so controllers with a single view no longer require a subfolder
• Request and controller action caching are bypassed in the event of an application (500) error

Breaking changes

• New default directory structure, but you can keep the old structure by editing the directory config
• The default rendering engine is now based on template literals, and consolidate is no longer included as a dependency by default
  • To use another template engine, install consolidate and your preferred package (handlebars, pug, etc.), then update config.citizen.templateEngine with the package name
• The handoff directive has been renamed to next
• The route property has been removed from the include directive
  • Route controller includes now accept a pathname string as shorthand for an included route
• Controller and request cache directives have changed in format and functionality
  • Cache directive properties are now action (formerly controller) and request (formerly route)
  • Cache request only applies if the controller action in which it's called is the action specified in the original request; subsequent controllers in the chain can no longer prompt a request cache
• The /type/direct URL parameter used to bypass controller handoff has been replaced with /direct/true
• The /direct/true URL parameter is no longer required to bypass the controller chain
  • Follow the partial naming convention by putting an underscore (_) at the beginning of the controller file name, and when requested from the client it will be rendered directly
  • /direct/true is still available to force controllers to bypass the chain
• The server request.start() event now fires before checking if the controller exists
  • This is logically consistent with the intention behind request.start() (i.e., it fires at the start of the request)
  • This allows you to incorporate logic into request.start() even if the requested controller doesn't exist (custom 404 handling, for example)
  • This is considered a breaking change because the request.start() context won't inherit the controller config like it did previously, so if you depend on anything in your controller config within the request.start() event, that functionality should be moved to the controller action itself, which fires after request.start()
• All instances of the enable property in the config have been renamed to enabled
• The sessions configuration setting is now an object that takes two arguments:
  • enabled (boolean)
  • lifespan (integer) - Reflects session timeout in minutes and replaces the old sessionTimeout property, which has been removed
• The form configuration setting has been renamed to forms
  • The dependency on formidable has been removed and replaced with basic native form parsing, see the docs for settings/options
  • Third-party form processors can still be used within hooks and controllers by accessing Node's native request object, which is passed to each hook and controller as an argument
• The log configuration setting has been renamed to logs
  • It now only applies to file logging, which can be enabled in development or production mode
  • Console debug logging is automatically enabled in development mode
• The urlPaths configuration option has been removed
  • It never worked reliably, and this sort of thing should really be handled by a proxy anyway
• The content directive, which contains all data local to the controller/view, has been renamed to local
  • Local variables within views should reference the local namespace (local.myVar)
• The legalFormat config option is now contentTypes
  • contentTypes is an array that lists available output MIME types ("text/html", "text/plain", "application/json", "application/javascript")
• The legalFormat directive has been removed
  • The new controller config mentioned above accepts the contentTypes option for setting available formats within a controller/action
• The format URL parameter (/format/json, etc.) has been removed
  • To request different output formats, the client must set the HTTP Accept request header to the desired content type (currently supported: text/html, text/plain, application/json, application/javascript)
• The request and response objects have been separated from the params object and are now passed into controllers as separate arguments
• params.route no longer contains the view, but it was wrong half the time anyway
  • You can reference params.route.chain for all controllers in the chain, including their actions, views, and context
• params.route.parsed.path is now params.route.parsed.pathname or params.route.pathname
• Controller action CORS configuration has been incorporated into the new controller/action configuration feature
• The output URL parameter for JSON requests has been removed
  • It added processing time and made view rendering more complex
  • The solutions to the problem solved by output include accessing controllers directly (underscore naming convention or /direct/true) and better API design in the first place
• JSON requests are now namespaced using the route controller name
  • A request that would have returned { "foo": "bar" } previously will now return { "index" : { "foo": "bar" } }
• The cache.set() overwrite option has been removed, as has the error/warning that occurred when attempting to overwrite existing cache items
• The file watcher options have changed to match chokidar's options, so adjust accordingly
• The ctzn_debug URL parameter is now a boolean that enables debug output in the view
  • Use the ctzn_inspect URL parameter to specify the variable you want to dump to the view
• The undocumented fallbackController option has been removed because there are better ways to handle a nonexistent controller in the app itself (citizen now returns a 404 by default)

0.9.2

• Moved commander to dependencies

0.9.1

• Added SameSite cookie attribute to the cookie directive (defaults to "Lax" as recommended by the spec)
• Fixed broken debug output
• Removed public helper methods that were deprecated in 0.8.0 and supposed to have been removed in 0.9.0
• Fixed typos in README
• Better handling of connections closed by client

0.9.0

New features:

• async-await support in controller actions

• Hot module reloading for controllers and models in development mode

  BREAKING CHANGES (see readme for details)

• Controller actions are now called as async functions, so you should use async-await syntax

• Thanks to the above, the manual passing of event emitters to return results and errors is no longer supported and has been removed (simple return and throw statements do the job now). This is a major breaking change that will require you to rewrite all your controllers and any function calls to which you pass the emitter. While this could be a massive headache depending on the size of your app, it's unquestionably an improvement, with simpler syntax and no clunky emitter handling.

• All helpers deprecated in 0.8.0 have been removed

• The syntax for the formats directive has been simplified and it has been renamed to "legalFormat" to distinguish it from the format url parameter

• The urlDelimiter option has been removed from JSON output (the delimiter is now a comma, because if you use a comma in a JSON key, you're insane)

• The headers directive has been renamed to "header", keeping the grammar consistent with other directives (cookie, session, etc.)

• Form configuration now has both a global config (set within your config file) and controller-action config (a new config object set within the controller module exports); syntax has changed from the previous global setting and maxFieldSize is now specified in kilobytes rather than megabytes

• CORS controller settings are under the new config module export

• Functionality previously under the debug mode has been moved to development mode and debug has been removed

• Log configuration has been streamlined and consolidated, with some log settings previously under the debug settings now moved to logs

• Invalid URL parameters in controller and route caches now always throw an error, but don't prevent rendering

• The directory for app event handlers has been renamed from "/on" to "/hooks".

0.8.8

• Fixed another bug in route cache retrieval

0.8.7

• Fixed a bug in route cache retrieval
• Tweaked readme

0.8.6

• Added request context to console output in the event of an error to assist with debugging
• Relaxed requirements on the route descriptor to allow dot (.) and tilde (~) characters
• Added event handler for connections closed by the client

0.8.5

• Added custom header check (x-citizen-uri) to provide the original requested URL to citizen when behind a proxy (nginx, apache, etc.), which fixes issues with ctzn_referer and secure cookies

0.8.4

• Fixed a bug in static file serving that caused initial requests for compressed static files to fail