Sys.Data
Sys.Data collects helpers for working with data: converting binary data between Base64, ArrayBuffer and Buffer, and listing the differences between two objects. Server-side code also gets virus scanning, file type detection and the Zod schema library. Client-side code also gets helpers that move items between lists in drag-and-drop handlers.
Availability: Everywhere
Functions
Section titled “Functions”toBase64()
Section titled “toBase64()”toBase64(binaryData: BinaryOrBase64): stringConverts binary data to a Base64 string. A string is assumed to be Base64 already and is returned unchanged.
| Parameter | Type | Description |
|---|---|---|
binaryData | BinaryOrBase64 | The data: an ArrayBuffer, Buffer, Uint8Array or Base64 string. |
Note
BinaryOrBase64 also includes File and Blob, but these throw Unsupported input type. In client-side code, a Uint8Array throws as well, because the browser has no Buffer; pass its buffer instead.
Returns: string · Availability: Everywhere
toArrayBuffer()
Section titled “toArrayBuffer()”toArrayBuffer(binaryData: BinaryOrBase64): ArrayBufferConverts binary data or a Base64 string to an ArrayBuffer. An ArrayBuffer is returned unchanged; for a Buffer, the result is a copy of exactly its bytes.
| Parameter | Type | Description |
|---|---|---|
binaryData | BinaryOrBase64 | The data: an ArrayBuffer, Buffer, Uint8Array or Base64 string. |
Note
As with toBase64(), File and Blob throw, and in client-side code a Uint8Array throws.
Returns: ArrayBuffer · Availability: Everywhere
toBuffer()
Section titled “toBuffer()”toBuffer(binaryData: BinaryOrBase64): BufferConverts binary data or a Base64 string to a Node.js Buffer. A Buffer is returned unchanged.
| Parameter | Type | Description |
|---|---|---|
binaryData | BinaryOrBase64 | The data: an ArrayBuffer, Buffer, Uint8Array or Base64 string. |
Note
Buffer exists only on the server. When this function runs on the client, it throws Buffer is not available in this environment.
Returns: Buffer · Availability: Everywhere
calculateObjectDifferences()
Section titled “calculateObjectDifferences()”calculateObjectDifferences(a: any, b: any, options?: CalculateDifferenceOptions, alreadyDiffedObjects?: PairwiseSet<any>): Difference[]Compares two objects and lists every property that was added, removed or changed from a to b, as Difference objects. Nested objects and arrays are compared property by property, so a change deep inside a shows up with its full path. For Entity and Static Entity instances, only the properties defined on the Business Object are compared.
| Parameter | Type | Description |
|---|---|---|
a | any | The old object. |
b | any | The new object. |
options | CalculateDifferenceOptions | Optional. Which properties to compare. |
alreadyDiffedObjects | PairwiseSet<any> | Optional. Pairs of objects that are already compared and are skipped. Lowgile uses it to avoid endless loops in circular structures; you normally leave it out. |
CalculateDifferenceOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
includeComputedProperties | boolean | Optional | Whether to compare computed (calculated) properties of Entity instances. Default: true. |
includeNotOfInterestProperties | boolean | Optional | Whether to compare Entity properties that are not marked as of interest, such as the system timestamps. Default: false. |
recurseIntoObjects | boolean | Optional | Whether an object that exists on one side only is listed property by property. With false, it is listed as one difference. Default: true. |
Note
An added or removed property whose value is falsy (0, false, '', null) is not listed.
const differences = Sys.Data.calculateObjectDifferences(oldRequest, newRequest)const summary = Sys.Data.Difference.formatListOfDifferences(differences, 'text')Returns: Difference[] · Availability: Everywhere
scanFileForViruses()
Section titled “scanFileForViruses()”scanFileForViruses(base: FsBasePath, pathComponents: string | string[]): Promise<VirusScanResult>Scans a file for viruses with the ClamAV scanner configured in the system setting System.AntiVirusScanner (host in location, port in port, default 3310). The file is addressed like in Sys.Fs. If the file doesn’t exist, the result is “not infected”.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Base directory the path is relative to, as in Sys.Fs. |
pathComponents | string | string[] | Path of the file below base, as one string or as path segments. |
Throws if the setting System.AntiVirusScanner has no location, or if the path is outside the directories app code may access.
Returns: Promise<VirusScanResult> · Availability: Server
scanFileForVirusesAndThrow()
Section titled “scanFileForVirusesAndThrow()”scanFileForVirusesAndThrow(base: FsBasePath, pathComponents: string | string[]): Promise<void>Scans a file like scanFileForViruses() and throws an error listing the found viruses if the file is infected.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Base directory the path is relative to, as in Sys.Fs. |
pathComponents | string | string[] | Path of the file below base, as one string or as path segments. |
Returns: Promise<void> · Availability: Server
scanBufferDataForViruses()
Section titled “scanBufferDataForViruses()”scanBufferDataForViruses(dataBuffer: Buffer): Promise<VirusScanResult>Scans binary data for viruses with the configured ClamAV scanner. Empty data counts as not infected.
| Parameter | Type | Description |
|---|---|---|
dataBuffer | Buffer | The data to scan. |
Returns: Promise<VirusScanResult> · Availability: Server
scanBufferDataForVirusesAndThrow()
Section titled “scanBufferDataForVirusesAndThrow()”scanBufferDataForVirusesAndThrow(dataBuffer: Buffer): Promise<void>Scans binary data like scanBufferDataForViruses() and throws an error listing the found viruses if it is infected.
| Parameter | Type | Description |
|---|---|---|
dataBuffer | Buffer | The data to scan. |
Returns: Promise<void> · Availability: Server
scanBase64DataForViruses()
Section titled “scanBase64DataForViruses()”scanBase64DataForViruses(dataBase64: string): Promise<VirusScanResult>Decodes Base64 data and scans it for viruses with the configured ClamAV scanner. An empty string counts as not infected.
| Parameter | Type | Description |
|---|---|---|
dataBase64 | string | The data, Base64-encoded. Leading and trailing whitespace is ignored. |
Throws Invalid data; base64 encoding expected if the string is not canonical Base64 (for example, if it contains line breaks or lacks padding).
Returns: Promise<VirusScanResult> · Availability: Server
scanBase64DataForVirusesAndThrow()
Section titled “scanBase64DataForVirusesAndThrow()”scanBase64DataForVirusesAndThrow(dataBase64: string): Promise<void>Scans Base64 data like scanBase64DataForViruses() and throws an error listing the found viruses if it is infected.
| Parameter | Type | Description |
|---|---|---|
dataBase64 | string | The data, Base64-encoded. |
Returns: Promise<void> · Availability: Server
scanTextDataForViruses()
Section titled “scanTextDataForViruses()”scanTextDataForViruses(text: string): Promise<VirusScanResult>Scans a text, encoded as UTF-8, for viruses with the configured ClamAV scanner. An empty string counts as not infected.
| Parameter | Type | Description |
|---|---|---|
text | string | The text to scan. |
Returns: Promise<VirusScanResult> · Availability: Server
scanTextDataForVirusesAndThrow()
Section titled “scanTextDataForVirusesAndThrow()”scanTextDataForVirusesAndThrow(text: string): Promise<void>Scans a text like scanTextDataForViruses() and throws an error listing the found viruses if it is infected.
| Parameter | Type | Description |
|---|---|---|
text | string | The text to scan. |
Returns: Promise<void> · Availability: Server
determineFileType()
Section titled “determineFileType()”determineFileType(bufferOrBase64: Buffer | string): Promise<{ extension: ExtensionType; mimeType: string;}>Detects the file type of binary data from its content (its “magic number”), not from a file name. Uses the package file-type (^21.3.4).
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64 | Buffer | string | The data, as a Buffer or a Base64 string. |
Note
If the type can’t be detected, for example for plain text, the promise resolves to null, although the declared type does not include null.
Returns: Promise<{ extension: ExtensionType; mimeType: string }> · Availability: Server
factorial()
Section titled “factorial()”factorial(n: number): bigintCalculates n! in native code. Results are correct only up to n = 33; larger values overflow.
| Parameter | Type | Description |
|---|---|---|
n | number | A non-negative integer. |
Returns: bigint · Availability: Server
transferArrayItem()
Section titled “transferArrayItem()”Re-export of transferArrayItem from Angular CDK drag-and-drop (@angular/cdk 22.2.3). It removes an item from one array and inserts it into another. See the Angular CDK drag-and-drop documentation.
Sys.Data.transferArrayItem(sourceList, targetList, sourceIndex, targetIndex)Availability: Client
copyArrayItem()
Section titled “copyArrayItem()”Re-export of copyArrayItem from Angular CDK drag-and-drop (@angular/cdk 22.2.3). It inserts a copy of an item from one array into another, leaving the source array unchanged. See the Angular CDK drag-and-drop documentation.
Sys.Data.copyArrayItem(sourceList, targetList, sourceIndex, targetIndex)Availability: Client
transferFromDropEvent()
Section titled “transferFromDropEvent()”transferFromDropEvent(event: CdkDragDrop<any>): voidMoves the dragged item from the list it was dragged from to the list it was dropped on, at the drop position. Both lists are taken from the drop event’s containers. Does nothing if the item was dropped where it started.
| Parameter | Type | Description |
|---|---|---|
event | CdkDragDrop<any> | The drop event of a drag-and-drop list. |
Returns: void · Availability: Client
copyFromDropEvent()
Section titled “copyFromDropEvent()”copyFromDropEvent(event: CdkDragDrop<any>): voidInserts the dragged item into the list it was dropped on, at the drop position, and leaves it in the list it was dragged from. Does nothing if the item was dropped where it started.
| Parameter | Type | Description |
|---|---|---|
event | CdkDragDrop<any> | The drop event of a drag-and-drop list. |
Returns: void · Availability: Client
Properties
Section titled “Properties”The Zod schema library, re-exported as-is from the package zod (^4.4.3). Use it to describe and validate the shape of data, for example data received from an external system. See the Zod documentation.
const Order = Sys.Data.Zod.object({ orderNumber: Sys.Data.Zod.string(), quantity: Sys.Data.Zod.number().int() })const order = Order.parse(JSON.parse(responseText))Availability: Server
Classes
Section titled “Classes”Difference
Section titled “Difference”One difference found by calculateObjectDifferences().
class Difference { path: (string | number)[]; oldValue: any; newValue: any; action: 'add' | 'remove' | 'change'; isOfInterest: boolean; isComputed: boolean;}| Property | Type | Description |
|---|---|---|
path | (string | number)[] | Property names and array indexes from the compared object down to the changed value. |
oldValue | any | Value in the old object; undefined for 'add'. |
newValue | any | Value in the new object; undefined for 'remove'. |
action | 'add' | 'remove' | 'change' | Whether the property was added, removed or changed. |
isOfInterest | boolean | Whether the Entity property is marked as of interest. true for plain objects. |
isComputed | boolean | Whether the Entity property is computed. false for plain objects. |
Availability: Everywhere
toString()
Section titled “toString()”toString(format?: 'text' | 'html', onlyLastPathPart?: boolean): stringDescribes the difference in one line, for example Changed amount from 100 to 120. Array indexes are shown counting from 1, as #1, and path parts are joined with →.
| Parameter | Type | Description |
|---|---|---|
format | 'text' | 'html' | Optional. 'html' wraps the parts in span elements with CSS classes starting with diff- and escapes the values. Default: 'text'. |
onlyLastPathPart | boolean | Optional. Whether to show only the last part of path instead of the full path. Default: false. |
Returns: string · Availability: Everywhere
formatListOfDifferences()
Section titled “formatListOfDifferences()”static formatListOfDifferences(differences: Difference[], format?: 'text' | 'html', formatFn?: (diff: Difference) => string): stringFormats a list of differences as an indented tree grouped by path: each nested object gets a heading line, and its differences are indented below it.
| Parameter | Type | Description |
|---|---|---|
differences | Difference[] | The differences, usually the result of calculateObjectDifferences(). |
format | 'text' | 'html' | Optional. 'text' joins lines with line breaks; 'html' returns nested div elements. Default: 'text'. |
formatFn | (diff: Difference) => string | Optional. Formats one difference. Default: diff.toString(format, true). |
Returns: string · Availability: Everywhere
VirusScanResult
Section titled “VirusScanResult”interface VirusScanResult { isInfected: boolean; viruses: string[];}Result of a virus scan: whether the data is infected, and the names of the viruses found.
Availability: Server
ExtensionType
Section titled “ExtensionType”type ExtensionType = '3g2' | '3gp' | '3mf' | '7z' | 'Z' | 'aac' | /* … */ | 'zip' | 'zst'The file extensions that determineFileType() can return, without the leading dot, such as 'pdf', 'png', 'docx' or 'zip'.
Availability: Server