@syncmatters/script-api 1.0.0

package/lib/script-error.d.ts

@@ -0,0 +1,38 @@
+import { CodedError } from "./coded-error.js";
+export declare enum ErrorCode {
+    None = "SCRIPT_NONE" /** default */,
+    InvalidOptionValue = "SCRIPT_INVALID_OPTION_VALUE",
+    InvalidArgumentValue = "SCRIPT_INVALID_ARG_VALUE",
+    InvalidConnectionId = "SCRIPT_INVALID_CONNECTION_ID",
+    InvalidConnectorCode = "SCRIPT_INVALID_CONNECTOR_CODE",
+    InvalidScriptCode = "SCRIPT_INVALID_SCRIPT_CODE",
+    InvalidObjectId = "SCRIPT_INVALID_OBJECT_ID",
+    InvalidIndexFilterValue = "SCRIPT_INVALID_INDEX_FILTER_VALUE",
+    InvalidCacheRowKeys = "SCRIPT_INVALID_CACHE_ROW_KEYS",
+    InvalidCachePageFormat = "SCRIPT_INVALID_CACHE_PAGE_FORMAT",
+    InvalidCacheStateProperty = "SCRIPT_INVALID_CACHE_STATE_PROPERTY",
+    InvalidFilePath = "SCRIPT_INVALID_FILE_PATH",
+    InvalidRelationshipId = "SCRIPT_INVALID_RELATIONSHIP_ID",
+    InvalidRelationshipType = "SCRIPT_INVALID_RELATIONSHIP_TYPE",
+    ResourceAlreadyClosed = "SCRIPT_RESOURCE_ALREADY_CLOSED",
+    InvalidEmailRecipients = "SCRIPT_INVALID_EMAIL_RECIPIENTS",
+    InvalidEmailSubject = "SCRIPT_INVALID_EMAIL_SUBJECT",
+    InvalidEmailBody = "SCRIPT_INVALID_EMAIL_BODY",
+    InvalidEmailAttachment = "SCRIPT_INVALID_EMAIL_ATTACHMENT",
+    InvalidSyncConfiguration = "SCRIPT_INVALID_SYNC_CONFIGURATION",
+    InvalidJsonPath = "SCRIPT_INVALID_JSON_PATH",
+    InvalidTimeZone = "SCRIPT_INVALID_TIME_ZONE",
+    ChildSyncFailure = "SCRIPT_CHILD_SYNC_FAILURE",
+    ColumnNotFound = "SCRIPT_COLUMN_NOT_FOUND",
+    UnexpectedRowCount = "SCRIPT_UNEXPECTED_ROW_COUNT",
+    UnexpectedRowId = "SCRIPT_UNEXPECTED_ROW_ID",
+    KvStoreShadowMismatch = "SCRIPT_KV_STORE_SHADOW_MISMATCH"
+}
+/**
+ * ConnectorError extends error to expose a meaningful error code e.g.
+ * const err = new ScriptError(ErrorCode.InvalidConnectionId, "supplied connectionId was not found");
+ */
+export declare class ScriptError extends Error implements CodedError {
+    readonly code: string;
+    constructor(code: ErrorCode, message?: any);
+}

package/lib/sync-group.d.ts

@@ -0,0 +1,85 @@
+/** Details of a source row and the related destination row */
+export interface MatchedRowPair {
+    srcRowId: string;
+    destRowId?: string;
+}
+export interface SyncGroupProcessSourceRowsOptions {
+    /** Optionally run a selected subset of syncs (blank means run all) */
+    syncUids?: Array<string>;
+    /** Skip the post-standard-run retry of stored sync errors. Defaults to false. */
+    skipRetryErrors?: boolean;
+}
+export interface SyncGroupProcessBySourceIdsOptions {
+    /** Sync to run */
+    syncUid: string;
+    /** Source rows to pass through the selected sync */
+    sourceRowIds: Array<string>;
+    /** Force the destination record add/update, bypassing any filter */
+    force?: boolean;
+}
+export interface SyncGroupProcessErrorsOptions {
+    /** Sync to run */
+    syncUid: string;
+    /** Source rows to pass through the selected sync */
+    sourceRowIds?: Array<string>;
+}
+export interface SyncGroup {
+    /** Run the sync group to process list/changed source rows, optionally for just some of the syncs that belong to the group */
+    processSourceRows(options: SyncGroupProcessSourceRowsOptions): Promise<void>;
+    /** Run the sync group to process selected source rows though a specific sync */
+    processBySourceIds(options: SyncGroupProcessBySourceIdsOptions): Promise<Array<MatchedRowPair>>;
+    /** Run the sync group to process source rows that have errors through a specific sync */
+    processErrors(options: SyncGroupProcessErrorsOptions): Promise<void>;
+    /** Stored errors for the sync group */
+    storedErrors: SyncGroupStoredErrors;
+    /** Stored matches for the sync group */
+    storedMatches: SyncGroupStoredMatches;
+    /** Stored checkpoints for the sync group */
+    storedCheckpoints: SyncGroupStoredCheckpoints;
+}
+export interface SyncGroupStoredCheckpoints {
+    /** Clear stored checkpoints for a specific sync or set of syncs */
+    clear(options: SyncGroupStoredCheckpointsClearOptions): Promise<void>;
+}
+export interface SyncGroupStoredCheckpointsClearOptions {
+    /** Clear all checkpoints from all syncs? */
+    clearAll?: boolean;
+    /** Syncs to clear checkpoints for (if not clearing all) */
+    syncs?: Array<{
+        syncUid: string;
+    }>;
+}
+export interface SyncGroupStoredErrors {
+    /** Clear stored errors for a specific sync or set of syncs */
+    clear(options: SyncGroupStoredErrorsClearOptions): Promise<void>;
+}
+export interface SyncGroupStoredErrorsClearOptions {
+    /** Closed reason for the errors */
+    closedReason: string;
+    /** Clear all errors from all syncs? */
+    clearAll?: boolean;
+    /** Syncs to clear errors for (if not clearing all) */
+    syncs?: Array<{
+        syncUid: string;
+        sourceRowIds?: Array<string>;
+    }>;
+}
+export interface SyncGroupStoredMatches {
+    /** Clear stored matches for a specific sync or set of syncs */
+    clear(options: SyncGroupStoredMatchesClearOptions): Promise<void>;
+}
+export interface SyncGroupStoredMatchesClearOptions {
+    /** Clear all matches from all syncs? */
+    clearAll?: boolean;
+    /** Syncs to clear matches for (if not clearing all) */
+    syncs?: Array<{
+        syncUid: string;
+        sourceRowIds?: Array<string>;
+    }>;
+}
+export interface SyncGroupStoredMatchesListOptions {
+    /** Sync to list matches for */
+    syncUid: string;
+    /** Source rows to list matches for (blank means list all) */
+    sourceRowIds?: Array<string>;
+}

package/lib/sync.d.ts

@@ -0,0 +1,392 @@
+import { Row, QueryRelatedFilter, QueryMatchFilter, QueryCheckpointFilter, UpsertCleanOptions, UpsertCleanResponse, ObjectFieldConstraints, JsonValuePath, RowMatchRuleType, Logger, Connection } from "../index.js";
+export type GroupRunMode = "Standard" | "SelectedIds" | "Errors";
+export type SyncOptimalBatchSizeOperation = "noFilter" | "idsFilter" | "relatedFilter" | "matchFilter" | "checkpointFilter" | "randomFilter" | "rowFilter" | "upsert" | "delete";
+export type SyncOptimalBatchSizeBatchType = "atomic" | "concurrent" | "splitInsertUpdateAtomic";
+export interface SyncOptimalBatchSizeResponse {
+    size: number;
+    batchType?: SyncOptimalBatchSizeBatchType;
+}
+/** details passed to an endpoint when starting a session */
+export interface SyncSession {
+    /** logger to use to capture data events */
+    log: Logger;
+    /** syncs endpoints that may exchange data during the session */
+    syncs: Array<SyncEndpointsSpecification>;
+}
+/** endpoints required by a sync */
+export interface SyncEndpointsSpecification {
+    /** org unique id of the sync */
+    syncUid: string;
+    /** platform id of the sync */
+    syncId: string;
+    source: {
+        /** type of the source */
+        type: "connection" | "script";
+        /** org specific id of source endpoint */
+        sourceUid: string;
+        /** endpoint specific id for the object */
+        primaryObjectUid: string;
+        /** primary object fields the sync expects to receive in query response (for mapping) */
+        fields?: Array<JsonValuePath>;
+        /** other objects to be considered when querying for rows changed since a checkpoint */
+        relatedObjectTriggers?: Array<{
+            objectUid: string;
+            relationshipUid?: string;
+        }>;
+        /** objects & fields the sync expects to receive in query-related responses */
+        relatedObjects?: Array<{
+            relationshipUid: string;
+            fields?: Array<JsonValuePath>;
+        }>;
+        /** lookup objects & fields the sync expects to receive in query-by-id responses */
+        lookupObjects?: Array<{
+            lookupUid: string;
+            fields?: Array<JsonValuePath>;
+        }>;
+    };
+    destination: {
+        /** type of the destination */
+        type: "connection" | "script";
+        /** org specific id of destination endpoint */
+        destinationUid: string;
+        /** endpoint specific id for the object */
+        primaryObjectUid: string;
+        /** primary object fields the sync expects to receive in query response (for mapping) */
+        fields?: Array<JsonValuePath>;
+        /** lookup objects & fields the sync expects to receive in query-by-id responses */
+        lookupObjects?: Array<{
+            lookupUid: string;
+            fields?: Array<JsonValuePath>;
+        }>;
+    };
+}
+/** Enpdoints must impliment this interface to exchange data with syncs */
+export interface SyncEndpoint {
+    /** called to allow an endpint to perform any required initialization */
+    sessionBegin(options: SyncSession): Promise<void>;
+    /** called [best effort] once all sync(s) have completed processing this sessions data */
+    sessionEnd(options: SyncSession): Promise<void>;
+    meta: {
+        /** retrieve details of the object on an endpoint */
+        objects: () => Promise<SyncEndpointObject[]>;
+        /** retrieve details of fields on an object */
+        fields: {
+            [uid: string]: () => Promise<SyncEndpointFields>;
+        };
+        /** retrieve details of relationships between object rows */
+        relationships: {
+            [uid: string]: (options: {
+                relationshipUids: Array<string>;
+            }) => Promise<Array<SyncEndpointObjectRelationship>>;
+        };
+        /** [optional] the endpoint can recommend a batch size to used when querying data */
+        optimalBatchSize: {
+            [uid: string]: (operation: SyncOptimalBatchSizeOperation, relatedFilter?: {
+                otherObjectId: string;
+                otherRelationshipId: string;
+            }, matchFilter?: RowMatchRuleType) => Promise<SyncOptimalBatchSizeResponse>;
+        };
+    };
+    /** query a stream of rows from the endpoint using standardized filters */
+    query: {
+        [uid: string]: (options: SyncQueryOptions) => SyncQueryResponse;
+    };
+    /** write a batch of rows to the endpoint */
+    upsert?: {
+        [uid: string]: (options: SyncUpsertOptions) => Promise<Row[]>;
+    };
+    /** write a batch of rows to the endpoint */
+    upsertClean?: {
+        [uid: string]: (options: SyncUpsertCleanOptions) => Promise<UpsertCleanResponse>;
+    };
+    /** delete a batch of rows from the destination endpoint */
+    delete?: {
+        [uid: string]: (options: SyncDeleteOptions) => Promise<void>;
+    };
+    /** the underlying connection that the endpoint is associated with */
+    connection?(): Connection;
+}
+/** describes a relationship between rows on an endpoint */
+export interface SyncEndpointObjectRelationship {
+    /** unique id for the relationship from this object to the other object (must be unique on this object) */
+    uid: string;
+    /** display label for the relationship (defaults to the uid) */
+    name?: string;
+    /** object id of the other object that has a relationship to this object */
+    relObjectUid: string;
+    /** maximum number of rows on this object that may be returned when this relation is queried for a given row on this object */
+    cardinality: "OneToOne" | "OneToMany";
+}
+export interface SyncEndpointObject {
+    uid: string;
+    name?: string;
+    canQuery?: boolean;
+    canQueryByIds?: boolean;
+    canQueryByCheckpoint?: boolean;
+    canQueryList?: boolean;
+    canUpsert?: boolean;
+    canDelete?: boolean;
+    canUpsertClean?: boolean;
+    canUpsertFieldOptions?: boolean;
+    canAddCustomRelationships?: boolean;
+    isCustom?: boolean;
+    matchRules?: RowMatchRuleType[];
+}
+/** data type of a field on an endpoint */
+export type SyncEndpointFieldDataType = "string" | "boolean" | "number" | "object" | "array" | "any";
+/** describes a field on an endpoint */
+export interface SyncEndpointField {
+    /** full path to the field value in dot notation */
+    path: string;
+    /** unique id for the field */
+    uid: string;
+    /** display label for the (defaults to the uid) */
+    name?: string;
+    /** sort order of the field */
+    order?: string;
+    /** data type of the field */
+    type: SyncEndpointFieldDataType;
+    /** for array fields, this defines the data type of each array element*/
+    arrayType?: SyncEndpointFieldDataType;
+    /** for option/picklist fields, these define the allowed values */
+    optionValues?: SyncEndpointFieldOptionValue[];
+    /** for option/picklist fields, can the option values be added to / updated? */
+    canUpdateOptions?: boolean;
+    /** field constraints */
+    constraints?: SyncEndpointFieldConstraints;
+    /** can this field be referenced in match rules? */
+    canMatch?: boolean;
+    /** indicates whether this field has child fields */
+    hasChildren?: boolean;
+    /** indicates this field holds the unique row id required when updating existing rows */
+    isId?: boolean;
+    /** indicates this field holds an object containing the user defined unique row identifier required
+     * for add and update operations, with an indication of the operation type */
+    isUserDefinedId?: boolean;
+    /** indicates this field is custom */
+    isCustom?: boolean;
+}
+export interface SyncEndpointFieldConstraints extends ObjectFieldConstraints {
+}
+/** describes an picklist option on an endpoint field */
+export interface SyncEndpointFieldOptionValue {
+    /** system specific unique id to use when referencing the option (insert/update/query) */
+    uid: string;
+    /** display label (defaults to the uid) */
+    name?: string;
+}
+/** describes fields present on an endpoint object */
+export interface SyncEndpointFields {
+    queryFields?: SyncEndpointField[];
+    queryFile?: boolean;
+    upsertFields?: SyncEndpointField[];
+    deleteFields?: SyncEndpointField[];
+}
+/** Sync passes these options to the endpoint when executing a query */
+export interface SyncQueryOptions {
+    /** logger to use to capture data events */
+    log: Logger;
+    /** limit the number of rows to return */
+    limit?: number;
+    /** include any file associated with each row? */
+    file?: boolean;
+    /** fields expected in the response */
+    fields?: Array<JsonValuePath>;
+    /** include fields needed to collect rows from selected relationships */
+    relationshipFields?: Array<string>;
+    /** retrieve a random sample of up to 'limit' records */
+    randomFilter?: boolean;
+    /** filter for rows by row id (key) */
+    idsFilter?: Array<string>;
+    /** filter for rows that relate to another objects rows on this endpoint */
+    relatedFilter?: QueryRelatedFilter;
+    /** filter for rows that meet a specific matching rule */
+    matchFilter?: QueryMatchFilter;
+    /** collect records changed since a particular checkpoint */
+    checkpointFilter?: QueryCheckpointFilter;
+    /** row filter options are system-specific and may extend the standard query options  */
+    rowFilter?: unknown;
+}
+/** Expected response from a sync query */
+export interface SyncQueryResponse {
+    rows: AsyncIterableIterator<Row>;
+    checkpoint?(): Promise<string | undefined>;
+}
+/** Sync passes these options to the endpoint when performing an upsert */
+export interface SyncUpsertOptions {
+    /** logger to use to capture data events */
+    log: Logger;
+    /** rows to send */
+    rows: Array<unknown>;
+}
+/** SyncUpsertCleanOptions holds the upsert record and options to control the process. */
+export interface SyncUpsertCleanOptions extends UpsertCleanOptions {
+    /** logger to use to capture data events */
+    log: Logger;
+}
+/** Sync passes these options to the endpoint when performing a delete */
+export interface SyncDeleteOptions {
+    /** logger to use to capture data events */
+    log: Logger;
+    /** rows to send */
+    rows: Array<unknown>;
+}
+/**
+ * SyncLogic holds custom logic to run as rows are passed through a sync.
+ */
+export interface SyncLogic {
+    /** Execute custom logic before the sync runs */
+    beforeRun?(ctx: SyncLogicBeforeRunContext): Promise<void>;
+    /** Inspect a source row with previously matched destination row  and return true to include in further processing. */
+    filterFast?(ctx: SyncLogicFilterFastContext): Promise<boolean>;
+    /**
+     * Inspect a source row with selected related rows, previously matched destination row and return true to include
+     * in further processing
+     * */
+    filterRelated?(ctx: SyncLogicFilterRelatedContext): Promise<boolean>;
+    /**
+     * Inspect a source row and matched destination rows. Filter and order the matched candidates to reject and/or prioritize
+     * preferred matches. The returned candidates will be checked, in returned order, and if not already matched to a different
+     * source row they will be selected as the best match.
+     */
+    reviewMatches?(ctx: SyncLogicSelectMatchContext): Promise<Array<unknown>>;
+    /**
+     * Inspect a source row with selected related rows, previously/new matched destination row and return true to include
+     * in further processing
+     * */
+    filterMatched?(ctx: SyncLogicFilterMatchedContext): Promise<boolean>;
+    /**
+     * Receive the source row, related rows (if any) and output row (if linked) and produce calculated field values for mapping.
+     */
+    calculate?(ctx: SyncLogicCalcContext): Promise<void>;
+}
+/** Defines how system fields are presented to the sync logic */
+export interface SyncSystemFields {
+    /** indicates that the source data is an array rather than an endpoint row */
+    sourceIsArrayElement?: boolean;
+    /** array element index (blank when not processing an array extracted from a source field) */
+    sourceArrayIndex?: number;
+    /** id of the primary source row being processed (blank if processing an array element) */
+    sourceRowId?: string;
+    /** id of the primary dest row being updated (blank if matched to an array element) */
+    matchedRowId?: string;
+    /** id of the unmatched dest row being processed (for loop related output) */
+    unmatchedArrayRowId?: string;
+    /** for looping syncs, id of the primary source row being processed */
+    parentSourceRowId?: string;
+    /** for looping syncs, id of the primary parent dest row being updated */
+    parentMatchedRowId?: string;
+}
+/** Defines how related rows are presented to the sync logic */
+export interface SyncRelatedFields {
+    [relUid: string]: unknown | Array<unknown>;
+}
+/** Defines how lookup results are presented to the sync logic */
+export interface SyncLookupFields {
+    [lookupUid: string]: unknown | Array<unknown>;
+}
+/** Defines how calculated fields are presented to the sync logic */
+export interface SyncCalculatedFields {
+    [fieldId: string]: unknown;
+}
+/** Context passed to custom sync logic when executing before the sync runs */
+export interface SyncLogicBeforeRunContext {
+    /** the mode of the sync group run */
+    groupRunMode: GroupRunMode;
+    /** logger to use to capture data events */
+    readonly log: Logger;
+    /** the source connection */
+    readonly srcConn?: () => Promise<Connection>;
+    /** the destination connection */
+    readonly destConn?: () => Promise<Connection>;
+    /** user (custom logic) defined state */
+    state: {
+        get(): Promise<unknown>;
+        set(state?: unknown): Promise<void>;
+    };
+    /** differential query checkpoints (if any) that will be used when the sync queries for rows */
+    checkpoint?: {
+        value: string | undefined;
+        relatedTriggers?: Array<{
+            objectUid: string;
+            relationshipUid: string;
+            value: string | undefined;
+        }>;
+    };
+}
+/** Context passed to custom sync logic when evaluating whether the src row should be excluded from processing */
+export interface SyncLogicFilterFastContext {
+    /** system fields relevant to the src row */
+    readonly system: SyncSystemFields;
+    /** the source row being passed through the sync */
+    readonly src: unknown;
+    /** parent primary source row when processing a loop array element */
+    readonly parent?: unknown;
+    /** the destination row that the src row was previously matched with, if any */
+    readonly dest?: unknown;
+    /** the caller requests that, if possible, filters be bypassed */
+    force?: boolean;
+}
+/** Context passed to custom sync logic when evaluating whether the src row should be excluded from processing */
+export interface SyncLogicFilterRelatedContext {
+    /** system fields relevant to the src row */
+    readonly system: SyncSystemFields;
+    /** the source row being passed through the sync */
+    readonly src: unknown;
+    /** parent primary source row when processing a loop array element */
+    readonly parent?: unknown;
+    /** rows related to the src row from relationships selected for this sync */
+    readonly related?: SyncRelatedFields;
+    /** the destination row that the src row was previously matched with, if any */
+    readonly dest?: unknown;
+    /** the caller requests that, if possible, filters be bypassed */
+    force?: boolean;
+}
+/** Context passed to custom sync logic when evaluating whether the src row should be excluded from processing */
+export interface SyncLogicFilterMatchedContext {
+    /** system fields relevant to the src row */
+    readonly system: SyncSystemFields;
+    /** the source row being passed through the sync */
+    readonly src: unknown;
+    /** parent primary source row when processing a loop array element */
+    readonly parent?: unknown;
+    /** rows related to the src row from relationships selected for this sync */
+    readonly related?: SyncRelatedFields;
+    /** rows related to the src row from lookups defined on this sync */
+    readonly lookups?: SyncLookupFields;
+    /** the destination row that the src row has been matched with, if any */
+    readonly dest?: unknown;
+    /** the caller requests that, if possible, filters be bypassed */
+    force?: boolean;
+}
+/** Context passed to custom sync logic when evaluating which, if any, matched destination row should be selected */
+export interface SyncLogicSelectMatchContext {
+    /** specification of the match rule that matched the src row to the candidates */
+    ruleSpec: {
+        /** the index of this match rule (0 is first) */
+        index: number;
+        /** the type of this match rule */
+        type: RowMatchRuleType;
+    };
+    /** the source row to match */
+    readonly src: unknown;
+    /** the candidate destination rows to match, sorted as per any user defined sort rules */
+    readonly candidates: Array<unknown>;
+}
+/** Context passed to custom sync logic when calculating custom field values  */
+export interface SyncLogicCalcContext {
+    /** system fields relevant to the src row */
+    readonly system: SyncSystemFields;
+    /** the source row being passed through the sync */
+    readonly src: unknown;
+    /** parent primary source row when processing a loop array element */
+    readonly parent?: unknown;
+    /** rows related to the src row from relationships selected for this sync */
+    readonly related?: SyncRelatedFields;
+    /** rows related to the src row from lookups defined on this sync */
+    readonly lookups?: SyncLookupFields;
+    /** the object to populate with calculated values for reference in the mapping phase */
+    calculated: SyncCalculatedFields;
+    /** the destination row that the src is matched with, if any */
+    readonly dest?: unknown;
+}

package/lib/utilities/csv-reader/csv-reader-csv-parse.d.ts

@@ -0,0 +1,16 @@
+import { CsvReader, CsvReaderOptions } from "./types.js";
+/**
+ * {@link CsvReader} using csv-parse: consume the parser as a Node async iterable instead of
+ * pause/resume + manual promises (same outcome as the fast-csv implementation, less machinery).
+ */
+export declare class CsvReaderCsvParse implements CsvReader {
+    #private;
+    constructor(options: CsvReaderOptions);
+    header(): Promise<string[]>;
+    jsDoc(): Promise<string>;
+    verifyHeader(required: string[]): Promise<void>;
+    rows(): AsyncIterableIterator<any>;
+    rowsWithProps(): AsyncIterableIterator<{
+        [name: string]: string;
+    }>;
+}

package/lib/utilities/csv-reader/csv-reader-fast-csv.d.ts

@@ -0,0 +1,15 @@
+import { CsvReader, CsvReaderOptions } from "./types.js";
+/**
+ * CsvReader implements the CsvReader interface using the fast-csv library.
+ */
+export declare class CsvReaderFastCsv implements CsvReader {
+    #private;
+    constructor(options: CsvReaderOptions);
+    header(): Promise<string[]>;
+    jsDoc(): Promise<string>;
+    verifyHeader(required: string[]): Promise<void>;
+    rows(): AsyncIterableIterator<any>;
+    rowsWithProps(): AsyncIterableIterator<{
+        [name: string]: string;
+    }>;
+}

package/lib/utilities/csv-reader/csv-reader.d.ts

@@ -0,0 +1,2 @@
+import { CsvReader, CsvReaderOptions } from "./types.js";
+export declare function createCsvReader(options: CsvReaderOptions): CsvReader;

package/lib/utilities/csv-reader/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./csv-reader.js";
+export * from "./types.js";

package/lib/utilities/csv-reader/types.d.ts

@@ -0,0 +1,48 @@
+import { FileProvider } from "../file-provider/file-provider.js";
+/**
+ * Options for the CsvReader
+ */
+export interface CsvReaderOptions {
+    /** source for the csv data */
+    source: {
+        /** read the data from a fileProvider */
+        fileProvider?: FileProvider;
+        /** read the data from a string */
+        string?: string;
+        /** read the data from a ReadableStream */
+        stream?: NodeJS.ReadableStream;
+    };
+    /** indicate whether a header line is absent */
+    noHeader?: boolean;
+    /**
+     * indicate whether to include empty rows/columns with whitespace
+     */
+    includeEmpty?: boolean;
+    /** delimiter that will separate columns. default "," */
+    delimiter?: string;
+    /** character used to quote fields the contain a delimiter */
+    quoteChar?: string;
+    /** character used to escape quotes inside a quoted field */
+    escapeChar?: string;
+    /** number of lines to skip at the beginning of the file */
+    skipLines?: number;
+    /** parse engine to use (default: 'fast-csv') */
+    parseEngine?: "fast-csv" | "csv-parse";
+}
+/**
+ * CsvReader parses a csv and emits an async iterator for accessing the next row. The row is an array
+ * allowing access to the fields by index or, if the csv has a header, by header name:
+ * for await (const row of reader.rows()) {
+ *   var field1ByName = row["my col name"];
+ *   var field1ByIndex = row[0];
+ *  }
+ */
+export interface CsvReader {
+    header(): Promise<string[]>;
+    jsDoc(): Promise<string>;
+    verifyHeader(required: string[]): Promise<void>;
+    rows(): AsyncIterableIterator<any>;
+    rowsWithProps(): AsyncIterableIterator<{
+        [name: string]: string;
+    }>;
+}

package/lib/utilities/csv-writer/csv-writer.d.ts

@@ -0,0 +1,21 @@
+import { FileProvider } from "../file-provider/file-provider.js";
+export interface CsvWriterOptions {
+    target?: {
+        filePath?: string;
+    };
+    noHeader?: boolean;
+    delimiter?: string;
+    quoteChar?: string;
+    escapeChar?: string;
+    prepend?: Buffer | Uint8Array;
+}
+/**
+ * CsvWriter writes rows or data to a csv file.
+ */
+export declare class CsvWriter {
+    constructor(options: CsvWriterOptions);
+    write(row: {
+        [col: string]: any;
+    } | string[]): Promise<void>;
+    close(): Promise<FileProvider>;
+}

package/lib/utilities/date-utils/date-utils.d.ts

@@ -0,0 +1,37 @@
+export declare function dateFormat(date: Date | number, options?: {
+    format?: "ISO" | "ISODate" | "yyyy-MM-dd HH:mm:ss" | "yyyyMMdd";
+    custom?: string;
+    tz?: string;
+}): string | undefined;
+export declare function dateParse(text: string, options?: {
+    format?: "ISO" | "ISODate" | "yyyy-MM-dd HH:mm:ss" | "yyyyMMdd";
+    custom?: string;
+    tz?: string;
+}): Date | undefined;
+export type DateTimeFormat = "none" | "unix" | "unix_ms" | "yyyy-MM-dd" | "M/d/yyyy" | "MM/dd/yyyy" | "dd/MM/yyyy" | "iso8601" | "yyyy-MM-dd HH:mm:ss" | "custom";
+export type DateTimeTrunc = "none" | "second" | "minute" | "hour" | "day" | "month" | "year";
+export type DateTimeInterval = "none" | "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "months" | "years";
+export interface DateTransformOptions {
+    /** Date/time value to parse */
+    input: string | number | undefined;
+    /** Format of the input Date/time string */
+    inputFormat: DateTimeFormat;
+    /** If the input format selected is 'custom' this must hold the format specification */
+    inputFormatCustom?: string;
+    /** Optional time zone of the input text */
+    inputTimeZone?: string;
+    /** Operators to apply to the parsed input before serializing */
+    dateTimeMath?: Array<{
+        count: number;
+        interval: DateTimeInterval;
+    }>;
+    /**Truncation rule to apply to the parsed input before serializing */
+    truncate?: DateTimeTrunc;
+    /** Format to output the Date/time string */
+    outputFormat?: DateTimeFormat;
+    /** If the output format selected is 'custom' this must hold the format specification */
+    outputFormatCustom?: string;
+    /** Optional time zone of the output value */
+    outputTimeZone?: string;
+}
+export declare function dateTransform(options: DateTransformOptions): string | number | undefined;