Knowledge Base: JavaScript Engine

• RavenDB integrates JavaScript scripting across various features, including:

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

• 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

• Execution context:
  Jint executes a JavaScript function on a single document at a time, with each execution running in isolation.
  Its processing context is limited to a single document, with no persistent execution state -
  even in patch operations, where it might appear to maintain continuity.

• Performance considerations:
  Since initializing the Jint engine is resource-intensive,
  RavenDB caches Jint instances based on user-defined scripts to reuse them and enhance performance.

• Execution limitations:

  • RavenDB limits the amount of statements that can be performed for each document processing.
    The default value is 10,000 and it can be set using the Patching.MaxStepsForScript configuration.
  • RavenDB limits the amount of cached Jint engines.
    The default value is 2,048 and it can be set using the Patching.MaxNumberOfCachedScripts configuration.
  • Recursive calls within scripts are limited to a depth of 64, a constant value that cannot be modified.

Predefined JavaScript functions

In addition to Jint's ECMAScript 5.1 implementation,
RavenDB provides the following set of predefined functions:

Document operations:

Method Signature	Return type	Description
id(document)	string	Returns the ID of the specified document<sup>[ex]</sup>.
load(documentId)	object	Returns the document with the given ID. Used in patching or ETL scripts.
load(documentId, collectionName)	object	Returns the document with the given ID. Used in JavaScript indexes.
loadPath(document, pathString)	object	Returns document(s) based on IDs found within the specified pathString in the given document. The pathString can be in a simple Foo.Bar form, in which case a single document is returned. A path like Foo.Bars[].Buzz can return an array of documents.
getMetadata(document)	object	Returns the metadata of the specified document, including properties like ChangeVector, ID, and LastModified.
lastModified(document)	number	Returns the number of milliseconds elapsed since the last modification time (UTC) of the specified document.
include(documentId)	Task	Used in RQL queries to include the document with the specified ID with the results.
put(documentId, document, [optional]changeVectorString)	Task	Creates or updates a document with the specified ID. To generate a new document ID, you can use the "collectionPrefix/Server-Side ID" notation<sup>[ex]</sup>.
This function can also clone an existing document. Note: attachments & counters will not be included in the clone<sup>[ex]</sup>. Used in patching.
del(documentId)	void	Deletes the document with the specified ID. Used in patching.
archived.archiveAt(document, dateString)	void	Schedules the specified document to be archived at the specified dateString. Used in patching.
archived.unarchive(document)	void	Unarchives the specified document. Used in patching.

Counter operations:

Method Signature	Return type	Description
counter(documentId, counterName)	number	Returns the value of the specified counter for the given document ID<sup>[ex]</sup>.
counter(document, counterName)	number	Returns the value of the specified counter for the given document<sup>[ex]</sup>.
incrementCounter(documentId, counterName, value)	void	Increments the specified counter for the given document ID. If the counter does not exist, it is implicitly created with the provided value. Counter values can be negative, allowing both increment and decrement operations<sup>[ex]</sup>.
incrementCounter(document, counterName, value)	void	Increments the specified counter for the given document. If the counter does not exist, it is implicitly created with the provided value. Counter values can be negative, allowing both increment and decrement operations<sup>[ex]</sup>.
deleteCounter(documentId, counterName)	void	Delete the specified counter from the given document ID<sup>[ex]</sup>.
deleteCounter(document, counterName)	void	Delete the specified counter from the given document<sup>[ex]</sup>.
counterRaw(documentId, counterName)	object	Returns a dictionary containing the counter value for each database node. The overall counter value is the sum of all node values.
counterRaw(document, counterName)	object	Returns a dictionary containing the counter value for each database node. The overall counter value is the sum of all node values.

Compare-exchange:

Method Signature	Return type	Description
cmpxchg(compareExchangeKey)	object	Returns the value stored in a Compare Exchange item for the specified key.

String manipulation:

Method Signature	Return type	Description
String.prototype.startsWith(searchString, position)	boolean	Returns true if the specified string starts with searchString at the given position. position is optional and defaults to 0.
String.prototype.endsWith(searchString, position)	boolean	Returns true if the specified string end with searchString at the given position. position is optional and defaults to 0.
String.prototype.padStart(targetLength, padString)	string	Pads the string from the start with padString (or whitespace by default) until it reaches targetLength.
String.prototype.padEnd(targetLength, padString)	string	Pads the string from the end with padString (or whitespace by default) until it reaches targetLength.
String.prototype.format(arg1, arg2, arg3 ...)	string	Formats the string by replacing occurrences of {[number]} with the corresponding argument based on a zero-based index.
startsWith(inputString, prefix)	boolean	Returns true if inputString starts with the specified prefix.
endsWith(inputString, suffix)	boolean	Returns true if inputString ends with the specified suffix.
regex(inputString, regex)	boolean	Returns true if inputString matches the specified regex pattern.

Arrays & objects:

Method Signature	Return type	Description
Array.prototype.find(function callback)	Array's element	Returns the first element in the array for which the callback function returns true.
Object.map(input, function mapFunction, context)	Array	Returns an array containing the results of mapFunction applied to all properties of input (or items, if input is an array). The mapFunction signature is function(itemValue, itemKey).

Mathematical operations:

Method Signature	Return type	Description
Raven_Min(num1, num2)	number	Returns the smaller of num1 and num2. If both params are of the same type (both numbers or both strings), a standard comparison is performed. If they are of mixed types (one number and one string), the string is parsed as a double for comparison. LazyNumberValue params resulting from method scalarToRawString are not supported.
Raven_Max(num1, num2)	number	Returns the larger of num1 and num2. If both params are of the same type (both numbers or both strings), a standard comparison is performed. If they are of mixed types (one number and one string), the string is parsed as a double for comparison. LazyNumberValue params resulting from method scalarToRawString are not supported.

Conversion operations:

Method Signature	Return type	Description
scalarToRawString(document, lambdaToField)	Raw field value. LazyStringValue for strings, LazyNumberValue for floating point numbers.	Returns the raw representation of a field. Useful for handling numbers that exceed the numeric or accuracy range of double (See Numbers in Jint), or for optimizing memory consumption when projecting large string values. The returned value is immutable.
convertJsTimeToTimeSpanString(ticksNumber)	string	Returns a human-readable TimeSpan representation of the specified ticksNumber.

Debugging:

Method Signature	Return	Description
output(message) or console.log(message)	void	Prints message to the debug output. Used for debugging single document patches.