Knowledge Base: JavaScript Engine

• Several RavenDB mechanisms incorporate JavaScript scripts:

  • RQL projections
  • Subscriptions
  • ETL
  • Smuggler (data import/export)
  • Single or Set based document patches
  • Time Series

• In order to execute JavaScript 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 functions 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, creates or updates a document with the given ID. In order to generate a new document ID it's possible to use "[collectionPrefix]/" Server-Side ID notation<sup>[ex]</sup>.
This function can also be used to clone an existing document (Note: Attachments & counters will not be added to the clone)<sup>[ex]</sup>.
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 inputString starts 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) or console.log(message)	void	Used for single document patches debug.
incrementCounter(documentId, counterName, value)	void	Increment the counter. If the chosen counter doesn't exists, it is implicitly created and its value is set to the <code>incrementCounter</code>'s <code>value</code>. A counter value can also be negative, so as the increment value<sup>[ex]</sup>.
incrementCounter(document, counterName, value)	void	Increment the counter. If the chosen counter doesn't exists, it is implicitly created and its value is set to the <code>incrementCounter</code>'s <code>value</code>. A counter value can also be negative, so as the increment value<sup>[ex]</sup>.
deleteCounter(documentId, counterName)	void	Delete the counter<sup>[ex]</sup>.
deleteCounter(document, counterName)	void	Delete the counter<sup>[ex]</sup>.
counter(documentId, counterName)	long	Get the counter value<sup>[ex]</sup>.
counter(document, counterName)	long	Get the counter value<sup>[ex]</sup>.
counterRaw(documentId, counterName)	long	Return a dictionary of counter value per database node (The overall value is a summary of all database node values).
counterRaw(document, counterName)	long	Return a dictionary of counter value per database node (The overall value is a summary of all database node values).