Skip to content

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

toBase64(binaryData: BinaryOrBase64): string

Converts binary data to a Base64 string. A string is assumed to be Base64 already and is returned unchanged.

ParameterTypeDescription
binaryDataBinaryOrBase64The 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(binaryData: BinaryOrBase64): ArrayBuffer

Converts 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.

ParameterTypeDescription
binaryDataBinaryOrBase64The 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(binaryData: BinaryOrBase64): Buffer

Converts binary data or a Base64 string to a Node.js Buffer. A Buffer is returned unchanged.

ParameterTypeDescription
binaryDataBinaryOrBase64The 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(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.

ParameterTypeDescription
aanyThe old object.
banyThe new object.
optionsCalculateDifferenceOptionsOptional. Which properties to compare.
alreadyDiffedObjectsPairwiseSet<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

FieldTypeRequiredDescription
includeComputedPropertiesbooleanOptionalWhether to compare computed (calculated) properties of Entity instances. Default: true.
includeNotOfInterestPropertiesbooleanOptionalWhether to compare Entity properties that are not marked as of interest, such as the system timestamps. Default: false.
recurseIntoObjectsbooleanOptionalWhether 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(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”.

ParameterTypeDescription
baseFsBasePathBase directory the path is relative to, as in Sys.Fs.
pathComponentsstring | 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(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.

ParameterTypeDescription
baseFsBasePathBase directory the path is relative to, as in Sys.Fs.
pathComponentsstring | string[]Path of the file below base, as one string or as path segments.

Returns: Promise<void> · Availability: Server

scanBufferDataForViruses(dataBuffer: Buffer): Promise<VirusScanResult>

Scans binary data for viruses with the configured ClamAV scanner. Empty data counts as not infected.

ParameterTypeDescription
dataBufferBufferThe data to scan.

Returns: Promise<VirusScanResult> · Availability: Server

scanBufferDataForVirusesAndThrow(dataBuffer: Buffer): Promise<void>

Scans binary data like scanBufferDataForViruses() and throws an error listing the found viruses if it is infected.

ParameterTypeDescription
dataBufferBufferThe data to scan.

Returns: Promise<void> · Availability: Server

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.

ParameterTypeDescription
dataBase64stringThe 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(dataBase64: string): Promise<void>

Scans Base64 data like scanBase64DataForViruses() and throws an error listing the found viruses if it is infected.

ParameterTypeDescription
dataBase64stringThe data, Base64-encoded.

Returns: Promise<void> · Availability: Server

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.

ParameterTypeDescription
textstringThe text to scan.

Returns: Promise<VirusScanResult> · Availability: Server

scanTextDataForVirusesAndThrow(text: string): Promise<void>

Scans a text like scanTextDataForViruses() and throws an error listing the found viruses if it is infected.

ParameterTypeDescription
textstringThe text to scan.

Returns: Promise<void> · Availability: Server

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).

ParameterTypeDescription
bufferOrBase64Buffer | stringThe 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(n: number): bigint

Calculates n! in native code. Results are correct only up to n = 33; larger values overflow.

ParameterTypeDescription
nnumberA non-negative integer.

Returns: bigint · Availability: Server

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

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(event: CdkDragDrop<any>): void

Moves 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.

ParameterTypeDescription
eventCdkDragDrop<any>The drop event of a drag-and-drop list.

Returns: void · Availability: Client

copyFromDropEvent(event: CdkDragDrop<any>): void

Inserts 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.

ParameterTypeDescription
eventCdkDragDrop<any>The drop event of a drag-and-drop list.

Returns: void · Availability: Client

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

One difference found by calculateObjectDifferences().

class Difference {
path: (string | number)[];
oldValue: any;
newValue: any;
action: 'add' | 'remove' | 'change';
isOfInterest: boolean;
isComputed: boolean;
}
PropertyTypeDescription
path(string | number)[]Property names and array indexes from the compared object down to the changed value.
oldValueanyValue in the old object; undefined for 'add'.
newValueanyValue in the new object; undefined for 'remove'.
action'add' | 'remove' | 'change'Whether the property was added, removed or changed.
isOfInterestbooleanWhether the Entity property is marked as of interest. true for plain objects.
isComputedbooleanWhether the Entity property is computed. false for plain objects.

Availability: Everywhere

toString(format?: 'text' | 'html', onlyLastPathPart?: boolean): string

Describes 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 →.

ParameterTypeDescription
format'text' | 'html'Optional. 'html' wraps the parts in span elements with CSS classes starting with diff- and escapes the values. Default: 'text'.
onlyLastPathPartbooleanOptional. Whether to show only the last part of path instead of the full path. Default: false.

Returns: string · Availability: Everywhere

static formatListOfDifferences(differences: Difference[], format?: 'text' | 'html', formatFn?: (diff: Difference) => string): string

Formats 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.

ParameterTypeDescription
differencesDifference[]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) => stringOptional. Formats one difference. Default: diff.toString(format, true).

Returns: string · Availability: Everywhere

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

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