/********************************************************************************************
 * SAILS.JS CHEATSHEET
 * REFERENCE: https://sailsjs.com/documentation/reference
 * CONCEPTS: https://sailsjs.com/documentation/concepts
 * APP STRUCTURE: https://sailsjs.com/documentation/anatomy
 *
 * 1. APPLICATION
 * 2. BLUEPRINT API
 * 3. COMMAND-LINE INTERFACE
 * 4. CONFIGURATION
 * 5. REQUEST
 * 6. RESPONSE
 * 7. WATERLINE ORM
 * 8. WEBSOCKETS
 ********************************************************************************************/

/********************************************************************************************
 * 1. APPLICATION
 * https://sailsjs.com/documentation/reference/application
 ********************************************************************************************/

// A dictionary of all loaded Sails models, indexed by their identity.
sails.models

// A dictionary of all accessible helpers, including organics.
sails.helpers

// A dictionary of all loaded Sails hooks, indexed by their identity.
sails.hooks

// The full set of configuration options for the Sails instance
// It is assembled automatically when Sails loads your app
// merging together command-line arguments, environment variables, your .sailsrc file,
// and the configuration objects exported from any and all modules in your app's config/ directory.
sails.config

// The runtime values of your app's custom configuration settings.
sails.config.custom

// A set of convenience methods for low - level interaction with connected websockets.
sails.sockets

// Talk to Socket.io directly.
sails.io

// A regular expression designed for use in identifying URL paths that seem like they are probably
// for a static asset of some kind (e.g. image, stylesheet, favicon.ico, robots.txt, etc).
sails.LOOKS_LIKE_ASSET_RX

// Return a dictionary of Sails actions.
sails.getActions()

// Look up the first route pointing at the specified target (e.g. MeController.login)
// and return a dictionary containing its method and URL.
sails.getRouteFor(target)

// Look up the first route pointing at the specified target (e.g. entrance/view-login)
// and return its URL.
sails.getUrlFor(target)

// Lift a Sails app programmatically.
// This does exactly what you might be used to seeing by now when you run sails lift.
sailsApp.lift(configOverrides, function(err) {})

// Load a Sails app into memory-- but without lifting an HTTP server.
// Useful for writing tests, command - line scripts, and scheduled jobs.
sailsApp.load(configOverrides, function(err) {})

// Shut down a lifted Sails app and have it cease listening for / responding to any future requests.
sails.lower(callback)

// Register a new Sails action that can then be bound to a route.
sails.registerAction(action, name)

// Register a new action middleware function that will be applied to actions
// with the specified identities.
sails.registerActionMiddleware(actionMiddlewareFns, actionIdentities)

// Flush and reload all Sails actions.
sails.reloadActions()

// Compile a view into an HTML template.
sails.renderView(pathToView, templateData)

// Make a virtual request to a running Sails instance.
sails.request(request)
sails.request(url, body)
sails.request(url, callback)
sails.request(url, body, callback)

// Access a particular datastore, or the default datastore.
sails.getDatastore(datastoreName)

// Log a message or some data at the "debug" log level using Sails' built-in logger.
sails.log(message)

/********************************************************************************************
 * 2. BLUEPRINT API
 * https://sailsjs.com/documentation/reference/blueprint-api
 ********************************************************************************************/

// Find a list of records that match the specified criteria
// and (if possible) subscribe to each of them.
GET /:model

// Look up the record with the specified id from the database
// and (if possible) subscribe to the record to hear about any future changes.
GET /:model/:id

// Populate and return foreign record(s) for the given association of this record.
GET /:model/:id/:association

// Create a new record in your database
// and notify subscribed sockets that a newly record is created
POST /:model

// Update an existing record in the database
// and notify subscribed sockets that it has changed.
PATCH /:model/:id

// Replace all of the foreign records in one of this record's collections
// and notify subscribed sockets to the parent record.
PUT /:model/:id/:association

// Add a foreign record to one of this record's collections
// and notify subscribed sockets to the parent record.
PUT /:model/:id/:association/:fk

// Delete the record specified by id from the database forever
// and notify subscribed sockets that a record has been deleted
DELETE /:model/:id

// Remove a foreign record from one of this record's collections
// and notify subscribed sockets about this removed child
DELETE /:model/:id/:association/:fk

/********************************************************************************************
 * 3. COMMAND-LINE INTERFACE
 * https://sailsjs.com/documentation/reference/command-line-interface
 ********************************************************************************************/

// Lift your Node.js/Sails.js app in interactive mode, and enter the REPL.
// Useful for trying out Waterline queries, quickly managing your data, and checking
// out your project's runtime configuration.
sails console [--dontLift]

// Generate api/models/Foo.js, including attributes with the specified types if provided.
sails generate model

// Generate a standalone action.
sails generate action

// Generate a helper at api/helpers/foo.js.
sails generate helper

// Generate api/controllers/FooController.js, including actions with the specified names if provided.
sails generate controller

// Generate a project hook in api/hooks/foo/.
sails generate hook

// Generate a foo folder containing the files necessary for building a new generator.
sails generate generator

// Generate a custom response at api/responses/foo.js
sails generate response

// Generate a api/adapters/foo/ folder containing the files necessary for building a new adapter.
sails generate adapter

// Generate a sails.io.js file at the specified location, overwriting the default sails.io.js if applicable.
sails generate sails.io.js

// Generate api/models/Foo.js and api/controllers/FooController.js.
sails generate api	

// Alias for sails new.
sails generate new

// Experimental. Adds the following files to your app:
// .gitignore, .jshintrc, .editorconfig, .npmignore, .travis.yml, .appveyor.yml
sails generate etc

// Attach the node debugger and lift the sails app; similar to running node--inspect app.js.
// You can then use a tool like the Chrome DevTools to interactively debug your apps.
sails inspect

// Run the Sails app in the current dir
// (if node_modules/sails exists, it will be used instead of the globally installed Sails)
sails lift [--prod] [--port <portNum>] [--verbose] [--silly]

// Create a new sails project.
sails new <yourAppName> [--no-frontend] [--minimal] [--without=package,package,package]

// Get the version of your computer's globally installed Sails command-line tool
// (i.e. the version you installed with npm install -g sails).
sails version

/********************************************************************************************
 * 4. CONFIGURATION
 * https://sailsjs.com/documentation/reference/configuration
 ********************************************************************************************/

// Determines which TCP port your Sails app will use to listen for incoming requests.
sails.config.port

// Declare the host name of your Sails app (By default, Sails will assume localhost).
sails.config.explicitHost

// The runtime “environment” of your Sails app (usually either development or production).
sails.config.environment

// A time limit, in milliseconds, imposed on all hooks in your app (default to 20000)
sails.config.hookTimeout

// Configure SSL settings for HTTPs and WSS
sails.config.ssl

// These configurable settings allow you to configure the blueprint API in Sails.
sails.config.blueprints

// Asynchronous bootstrap function that runs before your Sails app gets lifted (i.e. starts up).
// Can be used for setting up baseline data, running sanity checks on the status of your database...
sails.config.bootstrap

// Custom configuration for your app (one-off settings specific to your application)
// Things like the domain to use when sending emails, or 3rd party API keys for Stripe, Mailgun...
sails.config.custom

// Datastore configurations(or simply datastores) are like "saved settings" for your adapters.
sails.config.datastores

// Configuration for the global variables that Sails exposes by default.
sails.config.globals

// Configuration for your app's underlying HTTP server.
sails.config.http

// Configuration for Sails' built-in internationalization & localization features.
sails.config.i18n

// Configuration for the logger in your Sails app.
sails.config.log

// Your default project-wide model settings.
sails.config.models

// Dictionary that maps policies to an app’s actions.
sails.config.policies

// Configuration for custom (aka "explicit") routes.
sails.config.routes

// Configuration for your app's security settings.
sails.config.security

// Configuration for Sails's built-in session support.
sails.config.session

// Provide transparent access to Socket.io
sails.config.sockets

// Configuration for your app's server-side views.
sails.config.views

/********************************************************************************************
 * 5. REQUEST
 * https://sailsjs.com/documentation/reference/request-req
 ********************************************************************************************/

// The moment that Sails started processing the request, as a Javascript Date object.
req._startTime

// An object containing text parameters from the parsed request body, defaulting to {}.
// If a request contains one or more file uploads, only the text parameters sent before
// the first file parameter will be available in req.body.
req.body

// An object containing all of the unsigned cookies from this request (req).
req.cookies

// A flag indicating the user-agent sending this request (req) wants "fresh" data
// (as indicated by the "if-none-match", "cache-control", and/or "if-modified-since" request headers.)
req.fresh

// An object containing pre-defined/custom header given in the current request.
req.headers

// Returns the hostname supplied in the host HTTP header.
// This header may be set either by the client or by the proxy.
req.hostname

// The IP address of the client who sent this request (req).
req.ip

// Contains the IP addresses in this request's "X-Forwarded-For" header
// as an array of the IP address strings.
req.ips

// A flag indicating whether or not this request (req) originated from a Socket.io connection.
req.isSocket

// The request method (aka "verb".)
// All requests to a Sails server have a "method", even via WebSockets.
req.method

// Dictionary (plain JavaScript object) of request-agnostic settings available in your app's actions.
req.options

// Retains the original request URL allowing you to rewrite req.url freely for internal routing purposes.
// In almost all cases, you’ll want to use req.url instead.
req.originalUrl

// An object containing parameter values parsed from the URL path.
req.params

// The URL pathname from the request URL string of the current request (req).
req.path

// The protocol used to send this request (req).
req.protocol

// A dictionary containing the parsed query-string, defaulting to {}.
req.query

// Indicates whether or not the request was sent over a secure TLS connection (i.e. https:// or wss://).
req.secure

// A dictionary containing all of the signed cookies from this request (req).
req.signedCookies

// If the current Request (req) originated from a connected Socket.io client,
// req.socket refers to the raw Socket.io socket instance.
req.socket

// An array of all the subdomains in this request's URL.
req.subdomains

// Like req.path, but also includes the query string suffix.
req.url

// A flag indicating whether the requesting client would prefer a JSON response
// (as opposed to some other format, like XML or HTML.)
req.wantsJSON

// A flag indicating whether the current request (req) appears to be an AJAX request.
req.xhr

// Return whether this request (req) advertises that it understands the specified media type.
req.accepts(mediaType)

// Return whether this request (req) advertises that it is able to handle any of the specified
// character set(s), and if so, which one.
req.acceptsCharsets(charset1, charset2, …)

// Return whether this request (req) advertises that it understands any of the specified
// language(s), and if so, which one.
req.acceptsLanguages(language1, language2, …)

// Returns the value of all parameters sent in the request, merged together into a single dictionary
req.allParams()

// Build and return a Skipper Upstream representing an incoming multipart file upload from the specified field.
req.file(field)

// Returns the value of the specified header field in this request (req). Note that header names are case-insensitive.
req.get(header)

// Returns true if this request's declared "Content-Type" matches the specified media/mime type.
req.is(type)

// Returns the value of the parameter with the specified name.
req.param(name[, defaultValue])

// Override the inferred locale for this request.
req.setLocale(override)

// Time out this request if a response is not sent within the specified number of milliseconds.
req.setTimeout(numMilliseconds)

/********************************************************************************************
 * 6. RESPONSE
 * https://sailsjs.com/documentation/reference/response-res
 ********************************************************************************************/

// Indicate to a web browser or other user agent that an outgoing file download sent
// in this response should be "Saved as..." rather than "Opened", and optionally specify the
// name for the newly downloaded file on disk.
res.attachment([filename])

// This method is used to send a 200 ("OK") response back down to the client.
res.ok(data)

// This method is used to send a 400 ("Bad Request") response back down
// to the client indicating that the request is invalid.
res.badRequest(data)

// This method is used to send a 403 ("Forbidden") response back down
// to the client indicating that the request is not allowed.
res.forbidden()

// This method is used to send a 404 ("Not Found") response using either res.json() or res.view().
res.notFound()

// This method is used to send a 500 ("Server Error") response back down to the client indicating
// that some kind of server error occurred (i.e. the error is not the requesting user agent's fault).
res.serverError(err)
res.serverError()

// Sets a cookie with name (name) and value (value) to be sent along with the response.
res.cookie(name, value[, options])

// Clears cookie (name) in the response.
res.clearCookie(name[, options])

// Returns the current value of the specified response header (header).
res.get(header)

// Sets specified response header (header) to the specified value (value).
res.set(header, value)
res.set(headers)

// Sends a JSON response composed of a stringified version of the specified data.
res.json([statusCode,] data)

// Send a JSON or JSONP response.
res.jsonp()

// Sets the "Location" response header to the specified URL expression(url).
res.location(url)

// Redirect the requesting user-agent to the given absolute or relative url.
res.redirect(url)
res.redirect(statusCode, url)

// Send a string response in a format other than JSON (XML, CSV, plain text, etc.
// If you want to send a dictionary or JSON, use res.json().
// If you want to send a custom status code, call req.status() first.
res.send([string])

// Set the status code of this response.
res.status(statusCode)

// Sets the "Content-Type" response header to the specified type.
res.type(type)

// Respond with an HTML page.
res.view(pathToView, locals)
res.view(pathToView)
res.view(locals)
res.view()

/********************************************************************************************
 * 7. WATERLINE ORM
 * https://sailsjs.com/documentation/reference/waterline-orm
 ********************************************************************************************/

// --> DATASTORE <--

// Return the default datastore
var datastore = sails.getDatastore()

// The generic, stateless, low-level driver for this datastore (if the adapter supports it).
datastore.driver

// The live connection manager for this datastore.
datastore.manager

// Lease a new connection from the datastore for use in running multiple queries
// on the same connection (i.e. so that the logic provided in during can reuse the db connection).
await datastore.leaseConnection(during)

// Execute a raw SQL query using this datastore.
await datastore.sendNativeQuery(sql, valuesToEscape)

// Fetch a preconfigured deferred object hooked up to the sails-mysql or sails-postgresql adapter
// (and consequently the appropriate driver)
await datastore.transaction(during)

// --> MODELS <--

// Add one or more existing child records to the specified collection.
MyModel.addToCollection(parentId, association).members(childIds)

// Remove one or more members from the specified collection
MyModel.removeFromCollection()

// Replace all members of the specified collection
MyModel.replaceCollection()

// Archive ("soft-delete") records that match the specified criteria,
// saving them as new records in the built-in Archive model, then destroying the originals.
MyModel.archive(criteria)

// Archive ("soft-delete") the record that matches the specified criteria,
// saving it (if it exists) as a new record in the built-in Archive model, then destroying the original.
MyModel.archiveOne(criteria);

// Get the total number of records matching the specified criteria.
MyModel.count(criteria)

// Get the aggregate mean of the specified attribute across all matching records.
MyModel.avg(numericAttrName, criteria)

// Get the aggregate sum of the specified attribute across all matching records.
MyModel.sum(numericAttrName, criteria)

// Find records in your database that match the given criteria.
MyModel.find(criteria)

// Attempt to find a particular record in your database that matches the given criteria.
MyModel.findOne(criteria)

// Find the record matching the specified criteria.
// If no such record exists, create one using the provided initial values.
MyModel.findOrCreate(criteria, initialValues)

// Create a record in the database.
MyModel.create(initialValues)
MyModel.create(initialValues).fetch()  // Created record will be returned

// Create a set of records in the database.
MyModel.createEach(initialValues)
MyModel.createEach(initialValues).fetch()  // Created records will be returned

// Update all records matching criteria.
MyModel.update(criteria, valuesToSet)
MyModel.update(criteria, valuesToSet).fetch()  // Updated records will be returned

// Update the record that matches the given criteria, if one exists.
MyModel.updateOne(criteria).set(valuesToSet);

// Destroy records in your database that match the given criteria.
MyModel.destroy(criteria)
MyModel.destroy(criteria).fetch() // Destroyed record will be returned

// Destroy the record in your database that matches the given criteria, if one exists.
MyModel.destroyOne(criteria);

// Access the datastore for a particular model.
MyModel.getDatastore()

// Stream records from your database one at a time or in batches,
// without first having to buffer the entire result set in memory.
MyModel.stream(criteria)

// Verify that a value would be valid for a given attribute, then return it, loosely coerced.
MyModel.validate(attrName, value)

// --> QUERIES <--

// Set the maximum number of records to retrieve when executing a query instance.
query.limit(maximum)

// Indicate a number of records to skip before returning the results from executing a query instance.
query.skip(numRecordsToSkip)

// Set the order in which retrieved records should be returned when executing a query instance.
query.sort(sortClause)

// Specify a where clause for filtering a query.
query.where(whereClause)

// Tell Waterline (and the underlying database adapter) to send back records that were
// updated/destroyed/created when performing an .update(), .create(), .createEach() or .destroy()
// query. Otherwise, no data will be returned (or if you are using callbacks, the second argument
// to the .exec() callback will be undefined.)
// This is just a shortcut for .meta({fetch: true})
// Warning: This is not recommended for update/destroy queries that affect large numbers of records.
query.fetch()

// Modify a query instance so that, when executed, it will populate child records for the
// specified collection, optionally filtering by subcriteria. Populate may be called more than
// once on the same query, as long as each call is for a different association.
query.populate()

// Decrypt any auto-encrypted attributes in the records returned for this particular query.
// This is just a shortcut for .meta({decrypt: true})
query.decrypt()

// Execute a Waterline query instance.
query.exec(function (err, result) {})

// Begin executing a Waterline query instance and return a promise.
// This is an alternative to .exec().
query.toPromise()

// Capture and intercept the specified error, automatically modifying and re-throwing it,
// or specifying a new Error to be thrown instead. (Still throws.)
query.intercept(filter, handler)
query.intercept(handler)

// Provide additional options to Waterline when executing a query instance.
query.meta(options)

// Execute a Waterline query instance using promises.
// Whenever possible, it is recommended that you use await instead of calling this method.
// This is an alternative to .exec(). When combined with .catch(), it provides the same functionality.
query.then(callback)

// Execute a Waterline query instance using promises.
// Whenever possible, it is recommended that you use await instead of calling this method.
// This is an alternative to .exec(). When combined with .then(), it provides the same functionality.
query.catch(callback)

// Tolerate (swallow) the specified error, and return a new result value (or undefined) instead. (Don't throw.)
query.tolerate(filter, handler)
query.tolerate(filter)
query.tolerate(handler)

// Specify an existing database connection to use for this query.
query.usingConnection(connection)

/********************************************************************************************
 * 8. WEB SOCKETS
 * https://sailsjs.com/documentation/reference/web-sockets
 ********************************************************************************************/

// --> RESOURCEFUL PUBSUB (HIGHER LEVEL ABSTRACTION WHICH ARE USED BY SAILS BLUEPRINT API) <--

// Retrieve the name of the PubSub “room” for a given record.
MyModel.getRoomName(id)

// Broadcast an arbitrary message to socket clients subscribed to one or more of this model's records.
// Be sure and check req.isSocket === true before passing in req to refer to the requesting socket.
// If used, the provided req must be from a socket request, not just any old HTTP request.
// Is like sails.sockets.broadcast()
MyModel.publish(ids, data, req)

// Subscribe the requesting client socket to changes/deletions of one or more database records.
// Is like sails.sockets.join()
MyModel.subscribe(req, ids)

// Unsubscribe the requesting client socket from one or more database records.
// Is like sails.sockets.leave()
MyModel.unsubscribe(req, ids)

// --> SAILS.SOCKETS <--

// Subscribe all members of a room to one or more additional rooms.
// In a multi-server environment, the callback function (cb) will be executed when the
// .addRoomMembersToRooms() call completes on the current server. This does not guarantee that
// other servers in the cluster have already finished running the operation.
sails.sockets.addRoomMembersToRooms(sourceRoom, destRooms, cb)

// Broadcast a message to all sockets connected to the server (or any server in the cluster,
// if you have a multi-server deployment using Redis).
sails.sockets.blast(data)
sails.sockets.blast(eventName, data)
sails.sockets.blast(data, socketToOmit)
sails.sockets.blast(eventName, data, socketToOmit)

// Broadcast a message to all sockets in a room (or to a particular socket).
sails.sockets.broadcast(roomNames, data)
sails.sockets.broadcast(roomNames, eventName, data)
sails.sockets.broadcast(roomNames, data, socketToOmit)
sails.sockets.broadcast(roomNames, eventName, data, socketToOmit)

// Parse the socket ID from an incoming socket request (req).
sails.sockets.getId(req)

// Subscribe a socket to a room.
sails.sockets.join(socket, roomName)
sails.sockets.join(socket, roomName, cb)

// Unsubscribe a socket from a room.
sails.sockets.leave(socket, roomName)
sails.sockets.leave(socket, roomName, cb)

// Unsubscribe all members of a room (e.g. chatroom7) from that room and every other room
// they are currently subscribed to; except the automatic room associated with their socket ID.
sails.sockets.leaveAll(roomName, cb)

// Unsubscribe all members of a room from one or more other rooms.
sails.sockets.removeRoomMembersFromRooms(sourceRoom, destRooms, cb)

// --> SOCKET CLIENT <--

// Home of global configuration options for the sails.io.js library, as well as any sockets it creates.
io.sails

// Wait one cycle of the event loop after loading and then attempt to create a new SailsSocket
// and connect it to the URL specified by io.sails.url. 
io.sails.autoConnect

// Sockets will automatically (and continuously) attempt to reconnect to the server
// if they become disconnected unexpectedly.
io.sails.reconnection

// Dictionary of headers to be sent by default with every request from this socket.
// Can be overridden via the headers option in .request().
io.sails.headers

// Set an environment for sails.io.js, which affects how much information is logged to the console.
// Valid values are development (full logs) and production (minimal logs).
io.sails.environment

// The URL that the socket is connected to, or will attempt to connect to.
io.sails.url

// The transports that the socket will attempt to connect using.
io.sails.transports

// Used for creating new socket connections manually.
io.sails.connect([url], [options])

// Unbind the specified event handler (opposite of .on()).
// To force a client socket to stop receiving broadcasted messages, do not use this method.
// Instead, unsubscribe the socket in your server-side code:
// In order to use .off(), you will need to store the handlerFn argument you passed in to .on() in a variable.
io.socket.off(eventIdentity, handlerFn)

// Start listening for socket events from Sails with the specified eventName.
// Will trigger the provided callback function when a matching event is received.
// This happens when the server broadcasts a message to this socket directly, or to a room of which it is a member.
io.socket.on(eventName, function (msg) { })

// Send a virtual DELETE request to a Sails server using Socket.io.
io.socket.delete(url, data, function (data, jwres) {})

// Send a socket request(virtual GET) to a Sails server using Socket.io.
io.socket.get(url, data, function (resData, jwres) {})

// Send a socket request (virtual PATCH) to a Sails server using Socket.io.
io.socket.patch(url, data, function (resData, jwres) {})

// Send a socket request (virtual POST) to a Sails server using Socket.io.
io.socket.post(url, data, function (resData, jwres) {})

// Send a socket request (virtual PUT) to a Sails server using Socket.io.
io.socket.put(url, data, function (resData, jwres) {})

// Send a virtual request to a Sails server using Socket.io.
io.socket.request(options, function (resData, jwres) {})