@flatfile/implementation-utils-type-helpers

Provides common Typescript helpers for Flatfile Implementations.

Features

Guards

• isArrayOfType: A generic guard that checks if a value is an array of a specific type based on an input type guard.
• isStringArray: A guard that checks if a value is a string array.
• isMessage: A guard that checks if a value is a message in the format "__i" expects in the Flatfile v2/records.jsonl endpoint.

Type Derivation

• RowInputFromFields: Derives a row input from a sheet configuration, a row input contains only nullable string fields.
• RowFromFields: Derives a row type from a sheet configuration.
• RowStrict: Derives the keys of a sheet that have a specific constraint.

Usage

Working with isArrayOfType and isMessage

import {
  isArrayOfType,
  isMessage,
} from "@flatfile/implementation-utils-type-helpers";

const records = safe.records.stream({ sheetId: "someSheetId" });
const messages = isArrayOfType(records.first().get("__i"), isMessage);
// messages is now of type Message[]

Working with Type Derivation patterns.

Below is a pattern for defining a strongly typed sheet config and deriving the types from it.

import {
  RowInputFromFields,
  RowFromFields,
  RowStrict,
} from "@flatfile/implementation-utils-type-helpers";
import { SetFieldType, Merge, Simplify } from "type-fest";
import { SheetConfig } from "@flatfile/api/api";

export const FIELD_KEY_name = "name" as const;

export type UserFieldKey = typeof FIELD_KEY_NAME;

type UserField = SetFieldType<Flatfile.Property, "key", UserFieldKey>;

export type UserSheetConfig = Simplify<
  Merge<
    SheetConfig,
    {
      fields: UserField[];
    }
  >
>;

const userSheet: UserSheetConfig = {
  fields: [
    {
      key: FIELD_KEY_NAME,
      type: "string",
      constraints: [{ type: "required" }],
    },
  ],
} as const;

export type UserRecord = RowFromFields<typeof userSheet.fields>;
export type UserRecordInput = RowInputFromFields<typeof userSheet.fields>;
export type UserRecordStrict = RowStrict<typeof userSheet.fields, "required">;