Method Types

Sugar has 5 basic method types.

Modules

Although Sugar builds can now be customized at method level, modules are still used as an intuitive way of grouping similar methods. The main sugar npm package is organized into modules, which can be required together. Non-default modules are also excluded from the main Sugar build, but can be added by creating a customized build. Likewise, non-default modules (with the exception of ES5 as noted below) are not included in the sugar npm package, however can be included individually (i.e. sugar-language, etc).

Note that in the sugar npm package, ES5 polyfills are included, however must be explicitly required. Additionally, two builds are included in the dist/ directory, one with ES5 polyfills, and one without.

Extending

Sugar's core feature is its ability to extend native prototypes to allow working directly with enhanced Javascript objects. This functionality has changed from earlier versions to become opt-in and allow fine-grained control through the extend method. Individual namespaces such as Date or String can now be explictly included or excluded, as can individual methods.

When extending, methods on the Sugar global are mapped to their associated native depending on their type. For example, the instance method Sugar.Array.unique becomes Array.prototype.unique, while the static method Sugar.Array.create becomes Array.create. Note that Sugar will never extend methods onto Object.prototype by default. For more, see object methods.

Most methods listed above in the docs follow this pattern with the exception of polyfills – which are immediately applied to natives and do not go through extend – and accessors, which are static methods only called on the Sugar global.

If extend is called without special conditions (except, etc), then methods defined later will be immediately mapped so that extend does not need to be called multiple times.

Note that the Sugar global itself is an alias to extend to allow simpler syntax in Node environments (example below).

// Extend all methods
Sugar.extend();

// Extend all Date methods
Sugar.Date.extend();

// Extend specific namespaces
Sugar.extend({
  namespaces: [Date, String]
});

// Exclude specific namespaces
Sugar.extend({
  except: [Array, Number]
});

// Extend specific Array methods
Sugar.Array.extend({
  methods: ['first', 'last']
});

// Exclude specific Array methods
Sugar.Array.extend({
  except: ['unique', 'average']
});

// Node exports is an alias to .extend
require('sugar')();

To extend or not to extend?

Although Sugar has long been a proponent of safe extension of native Javascript objects, the decision to make this functionality opt-in is due to the fact that in the end there are still times when extending natives is not appropriate or desirable.

The most major of these is when developing a plugin or middleware. Although extending can be done safely, this should always be a conscious decision that the end user, or team, is well aware of. Extending natives in middleware means that its consumers may encounter issues because they are not aware that the global state has changed. If there is any chance that your code may be consumed later by a third party, it is strongly recommended not to use extend. Fortunately, chainables are now provided instead as a middle ground to allow working with Javascript objects in a similar manner without having to extend.

Sugar also believes that if native extension is to be done, it should be handled by a single library alone. Co-existing in the global namespace creates a potential for confusion caused by either library conflicting with the other's methods that simply isn't worth the value they provide. There are a number of libraries that augment natives, most often as a side-effect, and it is recommended that when using these libraries your project should not use extend.

Chainables

In situations where extending is not appropriate or desired, chainables can offer a nice middle ground to allow working with Javascript objects in a similar manner.

Chainables are very simple to use. They are created using the Sugar namespaces themselves, which double as constructor functions, by passing in a value that the chainable will wrap as a property called raw. This property is forwarded to both Sugar methods and native methods which exist on the chainable prototype. Accessing the raw property will retrieve the resulting value.

The Array and Date modules, when included, allow slightly enhanced chainable functionality by forwarding the constructor to their create method, allowing for some expressive shortcuts.

Note that chainable constructors are also factory functions as well, meaning that they do not require using the new keyword. Lastly, chainables also have a valueOf method that returns the raw property. This means that they can be used with vanilla Javascript operators. Note however that this will result in a raw value, which would have to be wrapped again to continue using as a chainable object.

var n = new Sugar.Number(5);
n.log().pow(2).round(2).raw;

var d = Sugar.Date('tomorrow');
d.addDays(5).relative().raw;

Sugar.String('foo') + Sugar.String('bar');

Polyfills

The ES5, ES6, and ES7 modules provide polyfill methods. These methods are mapped directly onto natives when functionality is broken or missing, and cannot be called directly on the Sugar global object. However, note that certain enhanced methods such as Array#map, have both spec-following polyfills found in the ES5 or ES6 module, and enhanced functionality that is provided elsewhere. The enhanced functionality works as with other normal Sugar methods – called either on the global object or on natives when extending. They do extra work to provide useful shortcuts, and finally call the native implementation under the hood.

Note that the ES5 module is not included in the default build. It can be added by creating a custom build.

Enhanced Methods

Some of Sugar's most powerful features are provided as "enhanced methods". These are methods that have the same name as built-in methods but allow arguments that would otherwise throw an error. For example, find and filter on Sugar.Array allow a string argument that is a shortcut to a function.

When extending natives with Sugar, having the same name effectively means that the built-in method will be overwritten. Sugar attempts to do this as cautiously as possible – only arguments that would otherwise throw an error are allowed, and anything else is immediately sent to the native implementation. In fact, in general, enhanced methods simply build up arguments to be handed off to the native implementation.

Nevertheless, overriding built-in methods is understandably controversial, so Sugar provides a way to opt-out of this behavior when extending. You can pass false for either the enhance flag to opt out of all enhancements, or a flag like enhanceArray to opt out of a specific namespace. Note that these flags simply prevent overriding built-in methods with the same name, so other methods with similar behavior will still be extended. For example, Array#none allows matching shortcuts, but is simply applying the inverse of Array#some. As there is no naming collision, this method will still be extended, even if the enhance flag is off. Also note that these enhancements can still be used any time when called as static methods on the Sugar global, or when using chainables.

Lastly, note that enhanced methods are defined first as polyfills, and again later in other modules, allowing the polyfill functionality to be consumed separately from the enhancement. For brevity they are only listed once in the method list.

Current enhancements include array matching shortcuts, deep property mapping, and enhancing String#includes to allow a regex.

users.map('name');

names.find(/^H/);

Sugar.extend({
  enhance: false // Disallow all enhancements
});

Sugar.extend({
  enhanceArray: false // Disallow Array enhancements
});

Object Methods

By default, Sugar will not touch Object.prototype as there are a number of associated risks that can easily create difficult to track down bugs, often in code you don't control. As a result, when extending, Object methods are mapped as static functions on the global (not the prototype).

However, object instance methods can still be enjoyed through the use of chainables. This usage replaces "extended objects" in previous versions of Sugar, and can greatly enhance the expressiveness of your code.

// Using static methods
Object.keys(Object.add(obj1, obj2))

// Using chainables
var obj = new Sugar.Object(obj1);
obj.add(obj2).keys().raw

Note that chainables can be used at any time, and do not touch native prototypes.

Finally, if you're feeling adventurous (and you generally have control over the code in your project) you can force Sugar to extend Object.prototype at your own risk using the objectPrototype flag. Note that even when using this flag the methods get and set are not extended as they have special meaning as prototype methods.

Sugar.extend({
  objectPrototype: true
});
obj1.add(obj2).keys();

Deep Properties

Methods that support deep properties will allow a dot or square brackets as special tokens. They will attempt to traverse into the object to retrieve the property, returning undefined if any namespace does not exist along the way.

Additionally, a .. separator inside the brackets is "range" notation, and will return the specified numerical range. Range members may be negative, which will be an offset from the end of the array.

In the case of Object.set, namespaces that do not exist will be created, and will be initialized to either an empty object or an empty array, depending on whether dot or square bracket syntax was used. The token [] carries the special meaning of "last index + 1", and effectively pushes the value onto the end of the array.

Object.get(users[0], 'currencies.usd.balance')

Object.get(users[0], 'profile.addresses[0].city')

Object.set(users[0], 'profile.addresses[2].city', 'Sao Paulo')

Object.set(users[0], 'profile.addresses[]', address)

users.average('currencies.usd.balance')

users.map('profile.addresses[0].street')

users.map('profile.addresses[-1].street')

users.map('profile.addresses[0..1].city')

Array Matching

A number of native Javascript array methods such as filter accept "matching functions" which match elements in the array by returning a boolean. Sugar takes this concept and enhances it by allowing shortcuts that build matching functions and hand them off to the native implemenation:

• Strings, numbers, and booleans will match using strict equality ===. These shortcuts can be used to find simple literals in an array of primitives.

• Arrays will perform deep matching when matching nested arrays.

• Regular expressions will call test to match against an array of strings.

• Dates will call getTime internally to match by time value.

• Plain objects perform "fuzzy matching", which matches specific properties. Object matchers can be as deep as necessary, and allow the same values listed above as well as functions, making complex matches possible. For example, if { name: /^[a-f]/ } is passed, it will match any object with a name property that starts with a-f.

• Non-plain objects such as DOM Elements or Events match by strict equality.

['a','b','c'].every('b')

['a','b','c'].some('b')

['a','b','c'].findIndex('b')

[[1,2],[5,6],[4,3]].findIndex([4,3])

names.find(/lly$/)

names.filter(/^H/)

users.find({ age: 32 })

Date Locales

Sugar is capable of both parsing and formatting dates in multiple locales. The default build includes English as the base locale. Additional locales can be added either by adding them in a custom build or by simply including the locale definition files after Sugar is loaded (in npm, these are in the locales directory). Once added, locales can be set globally with the setLocale method, or passed to methods:

// Set "en" as the global locale
Date.setLocale('en');

Date.create('一時間前', 'ja');

Date.create("d'ici 5 heures", 'fr');

jan.relative('ru');

new Date().short('fi');

new Date().medium('zh-CN');

new Date().long('es');

new Date().short('en')

new Date().short('en-US')

new Date().short('en-GB')

new Date().short('en-AU')

new Date().short('en-CA')

Modifying Locales

Sugar provides access to locale objects through getLocale. They are exposed mostly for introspection, as it is usually better to change the locale definition itself if possible. However, a method addFormat exists on the locale object to allow formats to be added at runtime. For more, see Date Parsing.

Creating Locales

If a locale is missing, it can be added with addLocale. This method takes a locale definition object. Refer to an existing locale as a good starting point for creating this object.

Most fields allow a simple alternating format to keep them compact. A colon : demarcates a prefix and pipe | indicates suffix alternation. For example, in the English definition file Sep:tember|t| is equivalent to September|Sept|Sep. Any alternate form will parse, but the order is important for date formatting as the first alternate will be the "full" form, and the second alternate will be the "abbreviated" form (tokens like {Mon} for {Month} or {Dow} for {Weekday}). Plural forms for units likewise use alternates when the definition has plural set to true.

Parsing formats are defined in parse, timeParse, and timeFrontParse. The last two will add time parsing tokens either on the front or back of the format. Any token demarcated with {} will become a capturing group. Adding ? to the token makes it optional, and | can also be used within the braces for alternation. Any regex token can be used between the curly brace tokens except for capturing groups, whose order is important to the regex parsing. For example, to have alternating tokens that are optional, use (?:{token1|token2})?. Tokens are listed in Date Parsing. Common tokens that are integral to a format but carry no value, such as "of" in English or "la" in French can be added to the "tokens" array, and accessed by a number signifying an index, such as {0}.

past, future, relative, and duration are output formats that allow formatting tokens (listed in Date Formatting, but may also be functions for grammatically complex languages (see Russian for an example). modifiers are special tokens that should be fairly easy to follow (see English for an example). For the edge modifier, values of -2 and 2 are the beginning of the unit and end of the unit respectively, where a value of 1 will effectively reset the time, so is used for the "last day of ...", which is not exactly the edge. -1 is unused.

Finally, if you have created a locale definition, please share it with the community by opening a pull request!

Ranges

Sugar ranges provide a lightweight, convenient way to handle a range of values or time that have a distinct start and end. All ranges have only a start and end as properties, but can be compared, combined, and iterated over.

Three types of ranges exist: Date, Number, and String. They are created through the range method on each namespace by passing a start and end value. Range methods appear in the API reference above and can be included or excluded in custom builds, however they differ from standard Sugar methods in that they are always called as instance methods on range objects, and never as static methods.

Note that ranges will accept a start value greater than the end. In this case iteration methods will count down instead of up. Other methods will function identically.

Number.range(5, 10).contains(8);

String.range('a', 'c').toArray();

Date.range(today, tomorrow).hours();

Date.range('Tuesday from 1pm to 6pm').hours();

Accessors

Accessor methods provide a way to access Sugar internals that affect multiple methods. For example, setting decimal in setOption on Number will control the decimal marker in number formats. Accessors are always called on the Sugar global object and are never extended onto natives.

The setOption accessor is a pattern that allows quick access to options specific to the namespace. Passing any value will override the option, while passing null will restore the default. This allows options to be quickly switched on and off.

Sugar.Number.setOption('decimal', ',');
Sugar.Number.format(49.95);

Sugar.String.addAcronym('SSL');
Sugar.String.camelize('ssl_error');

Array Sorting

Array#sortBy uses a number of sort options set in the setOption accessor. Default options provide the best possible results for the most major world languages, but can be modified. sortOrder is by default the following string:

AÁÀÂÃĄBCĆČÇDĎÐEÉÈĚÊËĘFGĞHıIÍÌİÎÏJKLŁMNŃŇÑOÓÒÔPQRŘSŚŠŞTŤUÚÙŮÛÜVWXYÝZŹŻŽÞÆŒØÕÅÄö

sortIgnore is null by default, so punctuation and other special characters will affect sorting. sortIgnoreCase is true by default so case will be ignored. Note however that the above ordering actually includes lowercase characters after uppercase (not shown), so if sortIgnoreCase is set to false, their order will still be properly respected.

sortEquivalents is a map containing diacritic (accented) letters that are known to be equivalents in major European languages, most notably French and German. This map can be modified simply by setting the properties, or reset by setting it to {}. Note that both cases must be specified separately. Equivalents are as follows (also includes lowercase equivalents):

• A: ÁÀÂÃÄ
• C: Ç
• E: ÉÈÊË
• I: ÍÌİÎÏ
• O: ÓÒÔÕÖ
• S: ß
• U: ÚÙÛÜ

Polish and Scandanavian Languages

The defaults handle most of the major world languages, however there are some exceptions. Polish orders the character Ç as a separate letter, while French treats it as a C. Also, Scandanavian languages like Swedish and Norwegian order Ä and Ö after Z, where German orders them as A and O. In such cases, simply removing that entry from the equivalents map will result in the correct order for these languages.

Other Limitations

Proper collation algorithms are complex, and can handle other situations which Sugar cannot. Most notably are expansions and contractions of multiple characters, such as ll in Spanish. In such cases, Array#sortBy itself may provide a workaround using the mapped sort value. For example, replacing ll with a distinct character or token and including it in sortOrder would solve the contraction issue for a strict Spanish sort. This works because the return value of the mapping function is only used for sort ordering and has no effect on actual content of the array. Expansions could likewise be added as required.

Support

Sugar features very robust support, and with the inclusion of polyfills will function in pre-ES5 environments down to IE 6-8. Sugar is tested in all major browsers (including mobile versions):

• Chrome
• Firefox
• Safari
• Opera
• Opera Mini
• Microsoft Edge
• Internet Explorer (6-11)