See on GitHub

    Knowledge Base: JavaScript Engine

    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[ex].
    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[ex].
    This function can also clone an existing document.
    Note: attachments & counters will not be included in the clone[ex]. Used in patching.
    del(documentId) void Deletes the document with the specified ID.
    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[ex].
    counter(document, counterName) number Returns the value of the specified counter for the given document[ex].
    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[ex].
    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[ex].
    deleteCounter(documentId, counterName) void Delete the specified counter from the given document ID[ex].
    deleteCounter(document, counterName) void Delete the specified counter from the given document[ex].
    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.

    related articlesRelated Articles

    Patching

    Querying

    Knowledge Base

    Home / Docs / Server / Kb / Javascript Engine