see on GitHub

Knowledge Base : JavaScript Engine


Several RavenDB mechanisms incorporate JavaScript scripts:

In order to execute javscript code, RavenDB uses Jint, an open source JavaScript interpreter, supporting ECMAScript 5.1.

In this page:
* How RavenDB uses Jint
* Predefined JavaScript functions


How RavenDB uses Jint

As mentioned before, RavenDB uses Jint to execute JavaScript code in a variety of operations.
In order to perform an operation, Jint receives a function to run and a single document to process, therefore, the processing context of Jint is a single document and there is no "long-term" execution context, even when it may look like it, in patch operations.
Jint engine initialization is an expansive operation, therefore, RavenDB caches Jint instances according to the user defined scripts and reuses them.

Execution limitations

RavenDB limits the amount of statements that can be performed for each document processing, it's default value is 10,000 and it can be set using the Patching.MaxStepsForScript configuration.
RavenDB limits the amount of cached Jint engines, it's default value is 2048, and it can be set using Patching.MaxNumberOfCachedScripts.
RavenDB limits the depth of recursive calls to 64, this value is a constant.

Predefined JavaScript functions

RavenDB introduced a set of predefined function, in addition to Jint's ECMAScript.1 implementation.

Method Signature Return type Description
id(document) string Returns document's ID.
load(documentId) object Returns the document with the given ID.
loadPath(document, pathString) Task Returns the document(s) according to the IDs that can be found in the given document, in the path pathString. The pathString can be of a simple Foo.Bar form, in that case, a single document will be returned. It also be of the form Foo.Bars[].Buzz, in that case it will return an array of documents, answering the path .
cmpxchg(compareExchangeKey) object Returns stored Compare Exchange value for the received key.
getMetadata(document) object Returns document's metadata, along with it's ChangeVector, ID and LastModified.
lastModified(document) long Returns document's last modified metadata value as total miliseconds of UTC .
include(documentId) Task<string> Used for RQL queries in order to include the document with the given ID with the results
del(documentId) void Used in patches, deletes the document with the given ID.
put(documentId, document, [optional]changeVectorString) Task Used in patches, saves a document with the given ID. This function can also be used for updating documents. In order to create a new document, it's possible to use "[collectionPrefix]/" Server-Side ID notation in order to generate a new document ID
String.prototype.startsWith(searchString, position) bool Returns true if at position the string starts with searchString.
String.prototype.endsWith(searchString, position) bool Returns true if at position the string end with searchString .
String.prototype.padStart(targetLength, padString) string Returns a new string, that padded from it's start by the string padString(or white-space by default), until it reaches the length targetlength. The function will repeat padString if needed.
String.prototype.padEnd(targetLength, padString) string Returns a new string, that padded from it's end by the string padString(or white-space by default), until it reaches the length targetlength. The function will repeat padString if needed.
String.prototype.format(arg1, arg2, arg3 ...) string Returns "formatted" string, that replaces all occurrences of {[number]} with an argument in the numbers place (using a zero based index).
startsWith(inputString, prefix) bool Returns true if inputStringstarts with prefix.
endsWith(inputString, suffix) bool Returns true if inputString ends with suffix.
regex(inputString, regex) bool Returns true if inputString matches regex regular expression.
Array.prototype.find(function callback) Array's element Returns the first array element, for which the callback function returns true.
Object.map(input, function mapFunction, context) Array Returns an array containing result of mapFunction process result of all input's properties (items, if it's an array). The mapFunction's signature is function(itemValue, itemKey)
Raven_Min(num1, num2) bool Find minimum out of num1 and num2. Parameters can be numbers or strings, but there is no raw number support (see scalarToRawString below). Strings will be parsed to double upon processing
Raven_Max(num1, num2) bool Find maximum out of num1 and num2. Parameters can be numbers or strings, but there is no raw number support (see scalarToRawString below). Strings will be parsed to double upon processing
convertJsTimeToTimeSpanString(ticksNumber) bool Returns human readable TimeSpan of the received ticksNumber.
scalarToRawString(document, lambdaToField) Raw field value (LazyStringValue for strings, LazyNumberValue for floating point numbers). Returns raw representation of a field. Useful when working with numbers that exceeds double's numeric or accuracy range. See Numbers in Jint. Also usefull for better memory consumption when projecting big string values. Note: returned value is immutable
output(message) void Used for single document patches debug.