can-util
Advanced tools
Common utilities for CanJS projects
can-util/dom Object
can-util/dom/ajax/ajax function
can-util/dom/child-nodes/child-nodes function
can-util/dom/class-name/class-name Object
can-util/dom/data/data Object
can-util/dom/dispatch/dispatch function
can-util/dom/document/document function
can-util/dom/events/events Object
can-util/dom/frag/frag function
can-util/dom/mutate/mutate Object
can-util/js Object
can-util/js/assign/assign function
can-util/js/base-url/base-url function
can-util/js/cid/cid function
can-util/js/deep-assign/deep-assign function
can-util/js/deparam/deparam function
can-util/js/diff/diff function
can-util/js/diff-object/diff-object function
can-util/js/each/each function
can-util/js/global/global function
can-util/js/import/import function
can-util/js/is-array-like/is-array-like function
can-util/js/is-browser-window/is-browser-window function
can-util/js/is-empty-object/is-empty-object function
can-util/js/is-node/is-node function
can-util/js/is-plain-object/is-plain-object function
can-util/js/is-promise/is-promise function
can-util/js/is-string/is-string function
can-util/js/is-web-worker/is-web-worker function
can-util/js/join-uris/join-uris function
can-util/js/make-array/make-array function
can-util/js/param/param function
can-util/js/string/string Object
can-util/js/string-to-any/string-to-any function
{Object}A collection of modules that operate on DOM.
Objectcan-util/dom/ajax/ajax functionajax(settings){Object}:
Configuration options for the AJAX request.
The list of configuration options is the same as for jQuery.ajax.{Promise}:
A Promise that resolves to the data.can-util/dom/child-nodes/child-nodes functionchildNodes(node)Get all of the childNodes of a given node.
var stache = require("can-stache");
var childNodes = require("can-util/child-nodes/child-nodes");
var html = "<div><h1><span></span></h1></div>";
var frag = stache(html)();
console.log(childNodes(frag)[0].nodeName); // -> DIV
{Object}:
The Node that you want child nodes for.{Object}Allows querying and manipulation of classes on HTML elements
var className = require("can-util/dom/class-name/class-name");
var fooDiv = document.createElement("div");
className.add(fooDiv, "foo");
fooDiv.outerHTML; //-> '<div class="foo"></div>'
ObjectclassName.add.call(el, cls)Add a class name to a DOM node if it is not already there.
className.add.call(el, "container");
{String}:
A string representing a single class name tokenreturns {void}:
className.has.call(el, cls)Determine wheter a DOM node has a given class name.
var isContainer = className.has.call(el, "container");
{String}:
A string representing a single class name token{Boolean}:
true if the element's class attribute contains the token, false otherwise.className.remove.call(el, cls)Remove a class name from a DOM node if it exists on the node
className.remove.call(el, "container");
{String}:
A string representing a single class name tokenreturns {void}:
{Object}Allows associating data as a key/value pair for a particular DOM Node.
var domData = require("can-util/dom/data/data");
ObjectdomData.cid.call(el)returns {Number}:
The value of the element's unique CID
Set a unique identifier for the dom node, using the undefined property.
domData.clean.call(el, key)Remove data from an element previously added by set
domData.clean.call(el, "metadata");
domData.get.call(el, key)Get data that was stored in a DOM Node using the specified key.
var metadata = domData.get.call(el, "metadata");
{String}:
A string used as a unique key for storing data associated with this DOM Node.domData.getCid.call(el)returns {Number}:
The value of the element's unique CID
Return the previously set unique identifier for the dom node.
domData.set.call(el, key, value){String}:
the key to store the value under{*}:
the value to store under the keySet data to be associated with a DOM Node using the specified key. If data already exists for this key, it will be overwritten.
domData.set.call(el, "metadata", {
foo: "bar"
});
can-util/dom/dispatch/dispatch functiondispatch.call(el, event, args, bubbles)Dispatch an event on an element.
{Object|String}:
An object specifies options applied to this event.{Array}:
Arguments passed into this event.{Boolean}:
Specifies whether this event should bubble (by default it will).can-util/dom/document/document functiondocument(document){Object}:
An optional document-like object
to set as the context's documentOptionally sets, and returns, the document object for the context.
var documentShim = { getElementById() {...} };
var domDocument = require("can-util/dom/data/data");
domDocument(documentShim);
...
domDocument().getElementById("foo");
{Object}Allows you to listen to a domEvent and special domEvents.
var domEvents = require("can-util/dom/events/events");
Object{events}Adds a listenable "attributes" event to DOM nodes, which fires when the node's attributes change.
events{events}Add delegate listeners to DOM events. Delegated listeners use a selector on an ancestor element to determine when to fire the event for an item. This can help cases where large numbers of similar DOM nodes are added into a DOM subtree, since event handlers do not have to be attached to each new node.
events{events}This event fires when nodes are added as descendants of the attached element
eventscan-util/dom/events/make-mutation-event/make-mutation-event functionmakeMutationEvent(specialEventNae, mutationNodesProperty){String}:
the event to handle as a mutation observer-based event{String}:
the property of interest in a DOM mutationThis function provides a simple interface to bind the DOM events interface to the mutation observer interface, by firing an event when a matching mutation is generated by the client
{events}This event fires when descendant elements of the bound element are detached or destroyed.
eventscan-util/dom/frag/frag functionConvert a String, HTMLElement, documentFragment, or contentArray into a documentFragment.
frag: function(item, doc)item {String|HTMLElement|documentFragment|contentArray}:
doc {Document}:
an optional DOM document in which to build the fragment
returns {documentFragment}:
{Object}Mutate an element by appending, inserting, and removing DOM nodes. Use this so that on the server "inserted" will be fired.
var mutate = require("can-util/dom/mutate/mutate");
var el = document.createElement("div");
el.addEventListener("inserted", function(){
console.log("Inserted was fired!");
});
mutate.appendChild.call(document.body, el);
Objectmutate.appendChild.call(el, child)Used to append a node to an element and trigger the "inserted" event on all of the newly inserted children. Since mutated takes an array we convert the child to an array, or in the case of a DocumentFragment we first convert the childNodes to an array and call inserted on those.
mutate.insertBefore.call(el, ref, child)Like mutate.appendChild, used to insert a node to an element before a reference node and then trigger the "inserted" event.
mutate.removeChild.call(el, child)Like mutate.appendChild, used to insert a node to an element before a reference node and then trigger the "removed" event.
mutate.replaceChild.call(el, child)Like mutate.appendChild and mutate.removeChild, used to replace a node with another node and trigger "removed" on the removed element and "inserted" on the inserted elements.
{Object}Utilities for manipulating JavaScript data structures.
Objectcan-util/js/assign/assign functionassign(target, source)A simplified version of Object.assign, which only accepts a single source argument.
var assign = require("can-util/js/assign/assign");
var obj = {};
assign(obj, {
foo: "bar"
});
console.log(obj.foo); // -> "bar"
{Object}:
The destination object. This object's properties will be mutated based on the object provided as source.{Object}:
The source object whose own properties will be applied to target.{Object}:
Returns the target argument.can-util/js/base-url/base-url functionbaseUrl(optionalBaseUrlToSet)Get and/or set the "base" (containing path) of the document.
var baseUrl = require("can-util/js/base-url/base-url");
console.log(baseUrl()); // -> "http://localhost:8080"
console.log(baseUrl(baseUrl() + "/foo/bar")); // -> "http://localhost:8080/foo/bar"
console.log(baseUrl()); // -> "http://localhost:8080/foo/bar"
{String}:
An optional base url to override reading the base URL from the known path.{String}:
Returns the set or computed base URLcan-util/js/cid/cid functioncid(object, optionalObjectType)Get a unique identifier for the object, optionally prefixed by a type name.
Once set, the unique identifier does not change, even if the type name changes on subsequent calls.
var cid = require("can-util/js/cid/cid");
var x = {};
var y = {};
console.log(cid(x, "demo")); // -> "demo1"
console.log(cid(x, "prod")); // -> "demo1"
console.log(cid(y)); // -> "2"
{Object}:
The object to uniquely identify.{String}:
An optional type name with which to prefix the identifier{String}:
Returns the unique identifiercan-util/js/deep-assign/deep-assign functiondeepAssign(target, [ ... sources ])Assign properties from a source object to a target object, deeply copying properties that are objects or arrays.
var deepAssign = require("can-util/js/deep-assign/deep-assign");
var dest = deepAssign({}, {
obj: {
foo: "bar"
}
}, {
arr: [{ hello: "world" }]
});
console.log(dest.obj.foo); // -> "bar"
{Object}:
The target object who's properties will be assigned from the source objects.{Object}:
Source objects from which properties will be assigned to the target object. Sources will be copied deeply; meaning any object or array properties will be traversed and copied (like a clone).can-util/js/deparam/deparam functiondeparam(params){String}:
a form-urlencoded string of key-value pairsreturns {Object}:
The params formatted into an object
Takes a string of name value pairs and returns a Object literal that represents those params.
var deparam = require("can-util/js/deparam/deparam");
console.log(JSON.stringify(deparam("?foo=bar&number=1234"))); // -> '{"foo" : "bar", "number": 1234}'
console.log(JSON.stringify(deparam("#foo[]=bar&foo[]=baz"))); // -> '{"foo" : ["bar", "baz"]}'
console.log(JSON.stringify(deparam("foo=bar%20%26%20baz"))); // -> '{"foo" : "bar & baz"}'
can-util/js/diff/diff functiondiff(oldList, newList){ArrayLike}:
the array to diff from{ArrayLike}:
the array to diff toreturns {Array}:
a list of Patch objects representing the differences
Returns the difference between two ArrayLike objects (that have nonnegative
integer keys and the length property) as an array of patch objects.
A patch object returned by this function has the following properties:
var diff = require("can-util/js/diff/diff");
console.log(diff([1], [1, 2])); // -> [{index: 1, deleteCount: 0, insert: [2]}]
console.log(diff([1, 2], [1])); // -> [{index: 1, deleteCount: 1, insert: []}]
can-util/js/diff-object/diff-object functiondiffObject(oldObject, newObject){Object}:
the object to diff from{Object}:
the object to diff toreturns {Array}:
an array of object-patch objects
Find the differences between two objects, based on properties and values
The object-patch object format has the following keys:
var diffObject = require("can-util/js/diff-object/diff-object");
console.log(diffObject({a: 1, b: 2}, {b: 3, c: 4})); // ->
[{property: "a", type: "remove"},
{property: "b", type: "set": value: 3},
{property: "c", type: "add", "value": 4}]
can-util/js/each/each functioneach(elements, callback, context)Loop over each element in an Array-Like data structure.
elements {Object|ArrayLike}:
callback {function(element, key, elements)}:
context {Object}:
the context object
returns {ArrayLike}:
the orignal array of elements
var each = require("can-util/js/each/each");
each([2,1,0], function(i) { console.log(this[i]); }, [4,5,6]); // -> 6 \n 5 \n 4
can-util/js/global/global functionGLOBAL()Returns the global that this environment provides. It will be one of:
windowselfglobalvar GLOBAL = require("can-util/js/global/global");
var g = GLOBAL();
// In a browser
console.log(g === window); // -> true
{Object}:
The global object for this JavaScript environment.can-util/js/import/import functionimportModule(moduleName, parentName)var importModule = require("can-util/js/import/import");
importModule("foo.stache").then(function(){
// module was imported
});
{String}:
The module to be imported.{String}:
A parent module that will be used as a reference for resolving relative module imports.{Promise}:
A Promise that will resolve when the module has been imported.can-util/js/is-array-like/is-array-like functionisArrayLike(obj)Determines if an object is "array like", meaning it can be looped over. Any object with a .length property is array like.
var isArrayLike = require("can-util/js/is-array-like/is-array-like");
// Arrays
console.log(isArrayLike([{ foo: "bar" }])); // -> true
// Strings
console.log(isArrayLike("some string")); // -> true
// Objects with .length property
console.log(isArrayLike({ length: 11 })); // -> true
// Numbers and Booleans are not.
console.log(isArrayLike(true)); // -> false
console.log(isArrayLike(13)); // -> false
{*}:
Any object type.{Boolean}:
True, if the object is similar to an array.can-util/js/is-browser-window/is-browser-window functionisBrowserWindow()Returns true if the code is running within a Browser window. Use this function if you need special code paths for when running in a Browser window, a Web Worker, or another environment (such as Node.js).
var isBrowserWindow = require("can-util/js/is-browser-window/is-browser-window");
var GLOBAL = require("can-util/js/global/global");
if(isBrowserWindow()) {
console.log(GLOBAL() === window); // -> true
}
{Boolean}:
True if the environment is a Browser window.can-util/js/is-empty-object/is-empty-object functionisEmptyObject(obj)Used to determine if an object is an empty object (an object with no enumerable properties) such as {}.
var isEmptyObject = require("can-util/js/is-empty-object/is-empty-object");
console.log(isEmptyObject({})); // -> true
console.log(isEmptyObject({ a: 1 })); // -> false
var obj = {};
Object.defineProperty(obj, "foo", {
enumerable: false,
value: "bar"
});
console.log(isEmptyObject(obj)); // -> true
{Object}:
Any object.{Boolean}:
True if the object is an object with no enumerable properties.can-util/js/is-node/is-node functionDetermines if your code is running in Node.js.
isNode()var isNode = require("can-util/js/is-node/is-node");
var GLOBAL = require("can-util/js/global/global");
if(isNode()) {
console.log(GLOBAL() === global); // -> true
}
{Boolean}:
True if running in Node.jscan-util/js/is-plain-object/is-plain-object functionisPlainObject(obj)Attempts to determine if an object is a plain object like those you would create using the curly braces syntax: {}. The following are not plain objects:
new keyword).var isPlainObject = require("can-util/js/is-plain-object/is-plain-object");
// Created with {}
console.log(isPlainObject({})); // -> true
// new Object
console.log(isPlainObject(new Object())); // -> true
// Custom object
var Ctr = function(){};
var obj = new Ctr();
console.log(isPlainObject(obj)); // -> false
{Object}:returns {Boolean}:
can-util/js/is-promise/is-promise functionisPromise(obj)Determines if an object is a Promise.
var isPromise = require("can-util/js/is-promise/is-promise");
var promise = new Promise(function(resolve){
resolve();
});
console.log(isPromise(promise)); // -> true
console.log(isPromise("foo bar")); // -> false
{Object}:
An object to be tested.{Boolean}:
True if the object is a Promise.can-util/js/is-string/is-string functionDetermines if the provided argument is a string.
isString(obj)var isString = require("can-util/js/is-string/is-string");
console.log(isString("foo")); // -> true
console.log(isString(String("foo")); // -> true
console.log(isString({})); // -> false
{*}:
An object to test if is a string.{Boolean}:
True if the object is a string.can-util/js/is-web-worker/is-web-worker functionDetermines if the code is running with a Web Worker.
isWebWorker()var isWebWorker = require("can-util/js/is-web-worker/is-web-worker");
var GLOBAL = require("can-util/js/global/global");
if(isWebWorker()) {
console.log(GLOBAL() === self); // -> true
}
{Boolean}:
True if running in a Web Worker.can-util/js/join-uris/join-uris functionJoin together a URI path to a base.
joinURIs(base, href)Provides a convenient way to join together URIs handling relative paths.
var joinURIs = require("can-util/js/join-uris");
var base = "http://example.com/some/long/path";
var href = "../../images/foo.png";
var res = joinURIs(base, href);
console.log(res); // -> http://example.com/images/foo.png
base {String}:
href {String}:
{String}:
The result of joining the two parts.can-util/js/make-array/make-array functionmakeArray(arr){ArrayLike}:
any array-like objectreturns {Array}:
a JavaScript array object with the same elements as the passed-in ArrayLike
makeArray takes any array-like object (can-list, NodeList, etc.) and converts it to a JavaScript array
can-util/js/param/param functionSerialize an object into a query string.
param(params)Serializes an object or array into a query string useful for making Ajax requests or the
browser. param handles nested objects and arrays. It uses encodeURIComponent to
escape values and keys.
param({a: "b", c: "d"}) //-> "a=b&c=d"
param({a: ["X","Y"]}) //-> "a[]=X&a[]=Y"
{Object}:
[description]{String}:
[description]can-util/js/set-immediate/set-immediate modulesetImmediate(function())cb {function}:
Polyfill for setImmediate() if it doesn't exist in the global context
{Object}String utilities used by CanJS libraries
Objectstring.esc(content){String}:
a string{String}:
the string safely HTML-escapedstring.getObject(name, roots, add){String}:
a String of dot-separated keys, representing a path of properties{Object|Array}:
the object to use as the root for property based navigation{Boolean}:
if true, add the parts at each step as new objectsreturns {*}:
the value at the property path descending from roots
Return the result of descending the path name through the properties of the object or objects
roots
If roots is an Array, each element of the array is evaluated, in order, until
the path is found in an element's properties (and properties-of-properties, etc.). Otherwise
roots is evaluated as the root object, returning either the object at the property path
descended from roots or undefined if any subpath is not found.
A path is a dot-delimited sequence of zero or more property names, such that "foo.bar" means "the property
'bar' of the object at the property 'foo' of the root." An empty path returns the first object in roots
if it's an array, roots itself otherwise.
If add is true and path is not found in any roots, a matching path that resolves to an empty object
is added to the first object in roots if roots is an array, roots itself otherwise.
var string = require("can-util/js/string/string");
console.log(string.getObject("a.b.c", {a: {b: {c: "foo"}}})); // -> "foo"
console.log(string.getObject("a.b.c", {a: {}})); // -> undefined
console.log(string.getObject("a.b", [{a: {}}, {a: {b: "bar"}}])); // -> "bar"
string.capitalize(s){String}:
the string to capitalizereturns {String}:
the supplied string with the first character uppercased if it is a letter
var string = require("can-util/js/string/string");
console.log(string.capitalize("foo")); // -> "Foo"
console.log(string.capitalize("123")); // -> "123"
string.camelize(s){String}:
the string to camelCasereturns {String}:
the supplied string with hyphens removed and following letters capitalized.
var string = require("can-util/js/string/string");
console.log(string.camelize("foo-bar")); // -> "fooBar"
console.log(string.camelize("-webkit-flex-flow")); // -> "WebkitFlexFlow"
string.hyphenate(s){String}:
a string in camelCasereturns {String}:
the supplied string with camelCase converted to hyphen-lowercase digraphs
var string = require("can-util/js/string/string");
console.log(string.hyphenate("fooBar")); // -> "foo-bar"
console.log(string.hyphenate("WebkitFlexFlow")); // -> "Webkit-flex-flow"
string.underscore(s){String}:
a string in camelCasereturns {String}:
the supplied string with camelCase converted to underscore-lowercase digraphs
var string = require("can-util/js/string/string");
console.log(string.underscore("fooBar")); // -> "foo_bar"
console.log(string.underscore("HTMLElement")); // -> "html_element"
string.sub(str, data, remove){String}:
a string with {curly brace} delimited property names{Object}:
an object from which to read propertiesreturns {String|null}:
the supplied string with delimited properties replaced with their values
if all properties exist on the object, null otherwise
If remove is true, the properties found in delimiters in str are removed from data.
var string = require("can-util/js/string/string");
console.log(string.sub("foo_{bar}", {bar: "baz"}})); // -> "foo_baz"
console.log(string.sub("foo_{bar}", {})); // -> null
can-util/js/string-to-any/string-to-any functionTurns a string representation of a primitive type back into the associated primitive.
stringToAny(string)Examines the provided string to see if it can be converted to a primitive type. Supported arguments are:
stringToAny("NaN"); // -> NaN
stringToAny("44.4"); // -> 44.4
stringToAny("false"); // -> false
{String}:
A string to convert back to its primitive type.{*}:
The primitive representation of the provided string.To make a build of the distributables into dist/ in the cloned repository run
npm install
node build
Tests can run in the browser by opening a webserver and visiting the test.html page.
Automated tests that run the tests from the command line in Firefox can be run with
npm test
FAQs
Common utilities for CanJS projects
The npm package can-util receives a total of 2,232 weekly downloads. As such, can-util popularity was classified as popular.
We found that can-util demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 16 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.