diff --git a/.travis.yml b/.travis.yml index 68bc948bb..b5ab59de7 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,7 +15,7 @@ node_js: - "10" - "12" - "14" - - "node" + - "16" branches: only: diff --git a/README.md b/README.md index 1b0e0f51e..87d418eca 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ Please read the [submission guidelines](http://sailsjs.com/documentation/contrib ## Contribute There are many different ways you can contribute to Sails: - answering questions on [StackOverflow](http://stackoverflow.com/questions/tagged/sails.js), [Gitter](https://gitter.im/balderdashy/sails), [Facebook](https://www.facebook.com/sailsjs), or [Twitter](https://twitter.com/search?f=tweets&vertical=default&q=%40sailsjs%20OR%20%23sailsjs%20OR%20sails.js%20OR%20sailsjs&src=typd) -- improving the [documentation](https://github.com/balderdashy/sails-docs#contributing-to-the-docs) or [website](https://github.com/balderdashy/www.sailsjs.com/issues) +- improving the [documentation](https://github.com/balderdashy/sails-docs#contributing-to-the-docs) - translating the [documentation](https://github.com/balderdashy/sails-docs/issues/580) to your native language - writing [tests](https://github.com/balderdashy/sails/blob/master/test/README.md) - writing a [tutorial](https://github.com/sails101/contribute-to-sails101), giving a [talk](https://speakerdeck.com/mikermcneil), or supporting [your local Sails meetup](https://www.meetup.com/find/?allMeetups=false&keywords=node.js&radius=Infinity&sort=default) diff --git a/docs/concepts/Helpers/Helpers.md b/docs/concepts/Helpers/Helpers.md index a6a4e2303..2785cd4b1 100644 --- a/docs/concepts/Helpers/Helpers.md +++ b/docs/concepts/Helpers/Helpers.md @@ -9,7 +9,7 @@ In Sails, helpers are the recommended approach for pulling repeated code into a For example, in the course of creating the actions that your Node.js/Sails app uses to respond to client requests, you will sometimes find yourself repeating code in several places. That can be pretty bug-prone, of course, not to mention annoying. Fortunately, there's a neat solution: replace the duplicate code with a call to a custom helper: ```javascript -var greeting = await sails.helpers.formatWelcomeMessage('Bubba'); +const greeting = await sails.helpers.formatWelcomeMessage('Bubba'); sails.log(greeting); // => "Hello, Bubba!" ``` @@ -44,7 +44,7 @@ module.exports = { fn: async function (inputs, exits) { - var result = `Hello, ${inputs.name}!`; + const result = `Hello, ${inputs.name}!`; return exits.success(result); } @@ -77,7 +77,7 @@ So, as you might expect, you can provide a default value for an input by setting The arguments you pass in when calling a helper correspond with the order of keys in that helper's declared `inputs`. Alternatively, if you'd rather pass in argins by name, use `.with()`: ```javascript -var greeting = await sails.helpers.formatWelcomeMessage.with({ name: 'Bubba' }); +const greeting = await sails.helpers.formatWelcomeMessage.with({ name: 'Bubba' }); ``` ##### Exits @@ -96,7 +96,7 @@ Imagine a helper called “inviteNewUser” which exposes a custom `emai For example, if this helper was called from within an action that has its own "badRequest" exit: ```javascript -var newUserId = sails.helpers.inviteNewUser('bubba@hawtmail.com') +const newUserId = sails.helpers.inviteNewUser('bubba@hawtmail.com') .intercept('emailAddressInUse', 'badRequest'); ``` @@ -141,7 +141,7 @@ inputs: { Then, to use your helper in your actions, you might write code like this: ```javascript -var headers = await sails.helpers.parseMyHeaders(req); +const headers = await sails.helpers.parseMyHeaders(req); ``` ### Generating a helper @@ -159,7 +159,7 @@ This will create a file `api/helpers/foo-bar.js` that can be accessed in your co Whenever a Sails app loads, it finds all of the files in `api/helpers/`, compiles them into functions, and stores them in the `sails.helpers` dictionary using the camel-cased version of the filename. Any helper can then be invoked from your code, simply by calling it with `await`, and providing some argin values: ```javascript -var result = await sails.helpers.formatWelcomeMessage('Dolly'); +const result = await sails.helpers.formatWelcomeMessage('Dolly'); sails.log('Ok it worked! The result is:', result); ``` @@ -170,11 +170,28 @@ sails.log('Ok it worked! The result is:', result); If a helper declares the `sync` property, you can also call it without `await`: ```javascript -var greeting = sails.helpers.formatWelcomeMessage('Timothy'); +const greeting = sails.helpers.formatWelcomeMessage('Timothy'); ``` But before you remove `await`, make sure the helper is actually synchronous. Without `await` an asynchronous helper will never execute! +##### Organizing helpers +If your application uses many helpers, you might find it helpful to group related helpers into subdirectories. For example, imagine you had a number of `user` helpers and several `item` helpers, organized in the following directory structure + +``` +api/ + helpers/ + user/ + find-by-username.js + toggle-admin-role.js + validate-username.js + item/ + set-price.js + apply-coupon.js +``` +When calling these helpers, each subfolder name (e.g. `user` and `item`) becomes an additional property layer in the `sails.helpers` object, so you can call `find-by-username.js` using `sails.helpers.user.findByUsername()` and you can call `set-price.js` with `sails.helpers.item.setPrice()`. + +> For more information, you can read a [conversation between Ryan Emberling and Mike McNeil](https://www.linkedin.com/feed/update/urn:li:activity:6998946887701565440?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A6998946887701565440%2C7000154787505668096%29) which goes into more detail about this use case, including some general tips and tricks for working with custom helpers and organics. ### Handling exceptions diff --git a/docs/concepts/ORM/Attributes.md b/docs/concepts/ORM/Attributes.md index ed896358d..6b7a2f4db 100644 --- a/docs/concepts/ORM/Attributes.md +++ b/docs/concepts/ORM/Attributes.md @@ -296,6 +296,8 @@ attributes: { Depending on your database, when using `unique: true`, you may also need set `required: true`. > When using `unique: true` on an attribute with the `utf8mb4` character set in a MySQL database, you will need to set the column size manually via the [`columnType` property](https://sailsjs.com/documentation/concepts/models-and-orm/attributes#?columntype) to avoid a possible 'index too long' error. For example: `columnType: varchar(100) CHARACTER SET utf8mb4`. + +