Waterline Models Plugin for Fluxible
A plugin for Fluxible applications to use the Waterline ORM on the client and server isomorphically.
The plugin exposes a
models property on the Fluxible ActionContext for performing Waterline queries in
action creators, and the
record data objects can be converted to record instances within a store.
This plugin wat built to allow using Sails.js model definitions isomorphically in Fluxible applications, but the plugin can also be used to initialize and interface with the Waterline ORM as a stand-alone component without Sails.
The only difference from the
sails.models object and the models object exposed on the context
is that this version has models indexed according to the all lowercase
identity as well as, if
globalID where capitalisation is maintained. This allows using
actionContext.models.ModelName which may be preferred over
If you are using this with Sails.js and aren't interested in all the details you can skip to the Use with Sails.js example at the end.
Because the plugin will be used on the server and client configuration must be provided for both. The option to set models initialised externally is also provided which will simply expose these models on the context, this will be the case when the plugin is used alongside Sails.js on the server.
It is assumed that the three de facto standard isomorphic startup scripts
client.js are used.
Options for configuring Waterline and registering models are shown below. Since the configuration may,
and probably will, be different on the
server options can be specified for either, and
jointly using the
common options where there is overlap. The specific options will be merge with the
common options to reach the final configuration. None of the three keys are required at any time.
var options =common:// Options to used on the server and client.modelDefaults:// All model definitions will be merged with these defaults.connection: 'inMemoryDb' // e.g. set a default connection for models, then override belowmodels:modelIdentity:identity: '' // Required: The key that will be used to retrieve the model// from `actionContext.models`.connection: '' // Required: The connection to use for persistence;// must match one of the connections.attributes: '' // Required: An object specifying the prototype// properties and methods.connections:inMemoryDb:adapter: 'sails-memory' // Required: The adapter used for this connection.// Additional connection settings.server:// Options merged with the common options for use on the server.client:// Options merged with the common options for use on the client.;
The model definitions on
models can be provided as an array or object.
The minimum configuration required before the ORM can be initialized is:
- For models: the
- For connections: a Waterline
For more details see the code example above and look at the Waterline- and Sails.js documentation.
If models will be initialised externally and set on the plugin using the
the configuration for that particular case (server or client) needn't be provided at all.
Configuring the ORM
Configuration options can be provided to the plugin constructor or set later using the
method. Options can be provided multiple times and will be merged.
;app;// More configuration later.app;
configure() method returns the plugin instance to allow fluent chaining.
Initialize/tearDown the ORM
Before using the models on the action context the ORM must be initialized. Once initialized the configuration may not be changed anymore.
Server Side Initialization
;var adapters = sailsMemory;app;
or if you prefer using promises you can do
adapters can be provided as an array or object.
Client Side Initialization
If a client configuration and client adapters have been provided the ORM will be initialized automatically when the Fluxible Context is rehydrated (see below).
If, however, client adapters have not been provided initialization can still be done in the
;const modelsPlugin = app;// Configure the plugin before rehydrationmodelsPlugin;app;
Before the plugin goes out of scope be sure to call
to close the connections to all adapters.
Set Client Adapters via the Plugin Constructor
Since the same adapters will likely not be used on the client and server especially the server adapters
should not be set in the common
app.js script since they would be bundled with the client side code
increasing the bundle size.
However, loading the client adapters on the server is less of an issue since they are loaded once when the Node.js process is started, and then don't affect server operation in any noteworthy way.
The plugin constructor therefore supports setting the client adapters early which can keep the
script cleaner by avoiding the need to access the plugin there at all.
// app.js;;var clientAdapters ='some-client-adapter': someClientAdapter;// Set the client options and adapters.app;// server.js;app;// client.js// Nothing to do here!
clientAdapters can be provided as an array or object.
Providing options is still optional even when client adapters are passed to the constructor:
Use with Sails.js
When using the plugin with Sails.js the model definitions will already be loaded and the server ORM
initialized. In this case the initialized models can be set directly and only the client configuration
needs to be provided. Importing the client adapters in the shared
app.js script means it will be
included in the client JS bundle.
// app.js;const clientAdapters = egSomeRestAdapter;// Initialize with client adapters here.app;// server.js// Get the model definitions (you might do this once at start-up and reuse this).sailsmodules;// client.js// Nothing to do here!
A client adapter that might be useful is waterline-sails.io.js which allows Waterline to communicate with the server using the sails.io.js web-socket client.
npm install npm test
PRs are welcome. Please add tests for any changes.
This software is free to use under the MIT license. See the LICENSE file for license text and copyright information.