From 7229dd499ec57428b50cb89f9ea41d42d32f77e0 Mon Sep 17 00:00:00 2001 From: danielle9897 Date: Wed, 5 Mar 2025 14:46:38 +0200 Subject: [PATCH] RDoc-2443 Fix review comments --- .../server/kb/javascript-engine.markdown | 124 +++++++++++++----- 1 file changed, 89 insertions(+), 35 deletions(-) diff --git a/Documentation/5.3/Raven.Documentation.Pages/server/kb/javascript-engine.markdown b/Documentation/5.3/Raven.Documentation.Pages/server/kb/javascript-engine.markdown index e019a46524..7705ef01c0 100644 --- a/Documentation/5.3/Raven.Documentation.Pages/server/kb/javascript-engine.markdown +++ b/Documentation/5.3/Raven.Documentation.Pages/server/kb/javascript-engine.markdown @@ -50,41 +50,95 @@ In addition to Jint's ECMAScript 5.1 implementation, RavenDB provides the following set of predefined functions: -| Method Signature | Return type | Description | -|-------------------------------------------------------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **id(document)** | `string` | Returns the ID of the specified document[[ex]](../../client-api/operations/patching/set-based#updating-by-document-id). | -| **load(documentId)** | `object` | Returns the document with the given ID. Used in [patching](../../client-api/operations/patching/single-document#loading-documents-in-a-script) or [ETL scripts](../../server/ongoing-tasks/etl/basics#transform). | -| **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. | -| **cmpxchg(compareExchangeKey)** | `object` | Returns the value stored in a [Compare Exchange](../../client-api/operations/compare-exchange/overview) item for the specified key. | -| **getMetadata(document)** | `object` | Returns the metadata of the specified document, including properties like `ChangeVector`, `ID`, and `LastModified`. | -| **lastModified(document)** | `number` | Returns the last modified metadata value as total milliseconds in UTC for the specified document. | -| **include(documentId)** | `Task` | Used in RQL [queries](../../client-api/session/querying/what-is-rql) to include the document with the specified ID with the results. | -| **del(documentId)** | `void` | Deletes the document with the specified ID. Used in [patching](../../client-api/operations/patching/set-based#updating-a-collection-name). | -| **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](../../server/kb/document-identifier-generation#strategy--2)"_ notation[[ex]](../../client-api/operations/patching/single-document#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document#clone-document).
Used in patching. | -| **String.prototype.startsWith(searchString, position)** | `boolean` | Returns _true_ if the specified string starts with `searchString` at the specified `position`. | -| **String.prototype.endsWith(searchString, position)** | `boolean` | Returns _true_ if the specified string end with `searchString` at the specified `position`. | -| **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. | -| **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)`. | -| **Raven_Min(num1, num2)** | `number` | Returns the smaller of `num1` and `num2`. Both parameters can be numbers or strings, but raw numbers are not supported (see `scalarToRawString` below).
Strings are parsed as double values during processing. | -| **Raven_Max(num1, num2)** | `number` | Returns the larger of `num1` and `num2`. Both parameters can be numbers or strings, but raw numbers are not supported (see `scalarToRawString` below).
Strings are parsed as double values during processing. | -| **convertJsTimeToTimeSpanString(ticksNumber)** | `string` | Returns a human-readable `TimeSpan` representation of the specified `ticksNumber`. | -| **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](../../server/kb/numbers-in-ravendb)), or for optimizing memory consumption when projecting large string values.
The returned value is immutable. | -| **output(message)** or **console.log(message)** | `void` | Prints message to the debug output. Used for debugging [single document patches](../../client-api/operations/patching/single-document). | -| **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]](../../client-api/operations/patching/single-document#increment-counter). | -| **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]](../../client-api/operations/patching/single-document#increment-counter). | -| **deleteCounter(documentId, counterName)** | `void` | Delete the specified counter from the given document ID[[ex]](../../client-api/operations/patching/single-document#delete-counter). | -| **deleteCounter(document, counterName)** | `void` | Delete the specified counter from the given document.[[ex]](../../client-api/operations/patching/single-document#delete-counter). | -| **counter(documentId, counterName)** | `number` | Returns the value of the specified counter for the given document ID[[ex]](../../client-api/operations/patching/single-document#get-counter). | -| **counter(document, counterName)** | `number` | Returns the value of the specified counter for the given document[[ex]](../../client-api/operations/patching/single-document#get-counter). | -| **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. | +--- + +#### **Functions for document operations**: + +| Method Signature | Return type | Description | +|-------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **id(document)** | `string` | Returns the ID of the specified document[[ex]](../../client-api/operations/patching/set-based#updating-by-document-id). | +| **load(documentId)** | `object` | Returns the document with the given ID.
Used in [patching](../../client-api/operations/patching/single-document#loading-documents-in-a-script) or [ETL scripts](../../server/ongoing-tasks/etl/basics#transform). | +| **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](../../client-api/session/querying/what-is-rql) 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](../../server/kb/document-identifier-generation#strategy--2)"_ notation[[ex]](../../client-api/operations/patching/single-document#add-document).
This function can also clone an existing document.
Note: attachments & counters will not be included in the clone[[ex]](../../client-api/operations/patching/single-document#clone-document). Used in patching. | +| **del(documentId)** | `void` | Deletes the document with the specified ID.
Used in [patching](../../client-api/operations/patching/set-based#updating-a-collection-name). | + +--- + +#### **Functions for counter operations**: + +| Method Signature | Return type | Description | +|------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **counter(documentId, counterName)** | `number` | Returns the value of the specified counter for the given document ID[[ex]](../../client-api/operations/patching/single-document#get-counter). | +| **counter(document, counterName)** | `number` | Returns the value of the specified counter for the given document[[ex]](../../client-api/operations/patching/single-document#get-counter). | +| **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]](../../client-api/operations/patching/single-document#increment-counter). | +| **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]](../../client-api/operations/patching/single-document#increment-counter). | +| **deleteCounter(documentId, counterName)** | `void` | Delete the specified counter from the given document ID[[ex]](../../client-api/operations/patching/single-document#delete-counter). | +| **deleteCounter(document, counterName)** | `void` | Delete the specified counter from the given document[[ex]](../../client-api/operations/patching/single-document#delete-counter). | +| **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. | + +--- + +#### **Functions for compare-exchange**: + +| Method Signature | Return type | Description | +|---------------------------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------| +| **cmpxchg(compareExchangeKey)** | `object` | Returns the value stored in a [Compare Exchange](../../client-api/operations/compare-exchange/overview) item for the specified key. | + +--- + +#### **Functions for 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. | + +--- + +#### **Functions for 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)`. | + +--- + +#### **Functions for 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. | + +--- + +#### **Functions for 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](../../server/kb/numbers-in-ravendb#numbers-in-javascript-engine)), 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`. | + + +--- + +#### **Functions for debugging**: + +| Method Signature | Return | Description | +|-------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------| +| **output(message)** or **console.log(message)** | `void` | Prints message to the debug output.
Used for debugging [single document patches](../../client-api/operations/patching/single-document). | {PANEL/}