web

web / lib/services/import-transforms

lib/services/import-transforms

Applies import transform rules to incoming data.

This service transforms raw import data (CSV rows, JSON objects, Excel rows) according to dataset-level transform rules, enabling flexible field mapping and schema evolution.

Transforms are applied before schema detection and validation, ensuring that incoming data is normalized to match the dataset’s canonical schema regardless of the source format.

Functions

applyTransforms()

applyTransforms(data, transforms): Record<string, unknown>

Apply transform rules to a data object.

Transforms are applied in the order they appear in the transforms array. Only active transforms are applied. The input data object is cloned to avoid mutations.

Parameters

data

Record<string, unknown>

The data object to transform (CSV row, JSON object, etc.)

transforms

ImportTransform[]

Array of transform rules to apply

Returns

Record<string, unknown>

Transformed data object with field mappings applied

Example

const data = { date: "2024-01-15", name: "Event" };
const transforms = [
  { type: "rename", from: "date", to: "start_date", active: true }
];
const result = applyTransforms(data, transforms);
// Returns: { start_date: "2024-01-15", name: "Event" }

getByPath()

getByPath(obj, path): unknown

Get value at path using dot notation.

Supports nested paths like “user.email” or “coordinates.0”. Returns undefined if any part of the path doesn’t exist.

Parameters

obj

unknown

The object to traverse

path

string

Dot-separated path string (e.g., “user.email”)

Returns

unknown

Value at the path, or undefined if not found

Example

const obj = { user: { email: "test@example.com" } };
getByPath(obj, "user.email"); // Returns: "test@example.com"
getByPath(obj, "user.phone"); // Returns: undefined

setByPath()

setByPath(obj, path, value): void

Set value at path using dot notation.

Creates nested objects as needed along the path. Supports setting values in nested structures.

Parameters

obj

Record<string, unknown>

The object to modify (mutated in place)

path

string

Dot-separated path string (e.g., “user.email”)

value

unknown

Value to set at the path

Returns

void

Example

const obj = {};
setByPath(obj, "user.email", "test@example.com");
// Result: { user: { email: "test@example.com" } }

deleteByPath()

deleteByPath(obj, path): void

Delete value at path using dot notation.

Removes the property at the specified path. Does nothing if the path doesn’t exist. Does not clean up empty parent objects.

Parameters

obj

Record<string, unknown>

The object to modify (mutated in place)

path

string

Dot-separated path string (e.g., “user.email”)

Returns

void

Example

const obj = { user: { email: "test@example.com", name: "John" } };
deleteByPath(obj, "user.email");
// Result: { user: { name: "John" } }

applyTransformsBatch()

applyTransformsBatch(dataArray, transforms): Record<string, unknown>[]

Apply transforms to an array of data objects.

Convenience function for batch processing. Each object is transformed independently.

Parameters

dataArray

Record<string, unknown>[]

Array of data objects to transform

transforms

ImportTransform[]

Array of transform rules to apply

Returns

Record<string, unknown>[]

Array of transformed data objects

Example

const rows = [
  { date: "2024-01-15", name: "Event 1" },
  { date: "2024-01-16", name: "Event 2" }
];
const transforms = [
  { type: "rename", from: "date", to: "start_date", active: true }
];
const result = applyTransformsBatch(rows, transforms);
// Returns array with start_date instead of date