open-index/open-npm huggingface dataset:
npm package: @flatfile/implementation-utils-job-worker
Description: Provides a class abstraction for easily implementing Flatfile Jobs
Author: Flatfile
Latest version: 0.0.14

# @flatfile/implementations-utils-job-worker

Provides a class abstraction for easily implementing Flatfile Jobs. This package simplifies the process of creating, running, and managing background jobs within the Flatfile ecosystem.

## Features

- **Abstract Worker Classes**: Provides `JobWorker`, `WorkbookJobWorker`, and `SheetJobWorker` to structure your job logic with easy access to event context.
- **Decorator-based Triggers**: Use the `@TriggeredBy` decorator to link your worker class to a specific job operation.
- **Progress Tracking**: Built-in `ProgressTracker` to report progress back to the Flatfile UI.
- **Simplified Error Handling**: `JobError` class for standardized error reporting.

## Usage

Here is an example of a simple job worker that processes records in a sheet.

```typescript
import {
  SheetJobWorker,
  TriggeredBy,
  worker,
} from "@flatfile/implementations-utils-job-worker";
import { FlatfileListener } from "@flatfile/listener";

// 1. Define your worker class
@TriggeredBy("processRecords", "sheet")
class ProcessRecordsJob extends SheetJobWorker {
  // `execute` is the main method where your job logic lives.
  async execute() {
    const { sheetId } = this;
    const sheet = await this.sheet();

    // Start progress tracking
    this.progress.add("Processing", { size: "l" });

    // Your business logic here...
    // For example, fetching records and processing them.
    await this.progress.report("Processing", 50, "Halfway there!");

    // ... more logic ...

    // Complete the progress
    await this.progress.complete("Processing", "Done!");

    return {
      outcome: {
        message: `Processing complete for sheet: ${sheet.name}.`,
      },
    };
  }
}

// 2. Register the worker with the listener
export default function (listener: FlatfileListener) {
  listener.use(worker(ProcessRecordsJob));
}
```

### Progress Tracking

The `ProgressTracker` helps you provide feedback to the user during long-running jobs.

- `progress.add(name, { size })`: Adds a new task to track. `size` can be `'s'`, `'m'`, or `'l'`.
- `progress.report(name, percentage, message)`: Updates the progress of a task.
- `progress.complete(name, message)`: Marks a task as 100% complete.
npm package: @flatfile/implementation-utils-known-resources
Description: Provides wrapper classes for common Flatfile API resources with convenient methods for common operations
Author: Flatfile
Latest version: 0.0.8

# @flatfile/implementations-utils-known-resources

Provides wrapper classes for common Flatfile API resources with convenient methods for common operations. These classes simplify interactions with Workbooks and Sheets.

## Features

-   **`KnownWorkbook`**: A wrapper around `Flatfile.Workbook` that provides helpful methods for accessing sheets.
-   **`KnownSheet`**: A wrapper around `Flatfile.Sheet` that provides easy access to sheet properties and fields.

## Usage

Instead of working directly with the raw API response objects, you can use these classes to make your code more readable and robust.

### Working with `KnownWorkbook`

Here's how you can get a workbook and interact with its sheets:

```typescript
import { FlatfileClient } from "@flatfile/api";
import { KnownWorkbook } from "@flatfile/implementations-utils-known-resources";

const api = new FlatfileClient();

async function getWorkbookAndSheets(workbookId: string) {
  // Fetch the raw workbook object from the API
  const { data: rawWorkbook } = await api.workbooks.get(workbookId);

  // Wrap it in a KnownWorkbook
  const workbook = new KnownWorkbook(rawWorkbook);

  // Access sheets easily
  const allSheets = workbook.sheets; // Returns an array of KnownSheet objects

  // Check if a sheet exists by its slug
  if (workbook.hasSheet("contacts")) {
    // Get a specific sheet by its slug
    const contactsSheet = workbook.sheet("contacts");

    console.log(`Sheet Name: ${contactsSheet.name}`);
    console.log(`Sheet ID: ${contactsSheet.id}`);

    // Get all field keys for the sheet
    const fieldKeys = contactsSheet.keys();
    console.log("Fields:", fieldKeys);
  }
}
```
npm package: @flatfile/implementation-utils-type-helpers
Description: Provides common Typescript helpers for Flatfile Implementations
Author: Flatfile
Latest version: 0.0.4

# @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`

```typescript
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.

```typescript
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">;
```
npm package: @flatfile/listener
Description: A PubSub Listener for configuring and using Flatfile
Latest version: 1.1.2

# @flatfile/listener

`@flatfile/listener` is Flatfile's core library. It combines event handling capabilities with Flatfile-specific functionality, such as working with Flatfile records and sessions. Simply put, it receives events and it responds to events. Period.

The `AuthenticatedClient` class serves as a foundation for authenticated API communication, while the event-related classes enable event-driven workflows within the Flatfile ecosystem.

## Components

Here's an overview of the package and its components:

### `FlatfileRecord and FlatfileRecords`

- These classes represent records and collections of records in the Flatfile format.
- They provide methods for manipulating and retrieving record data.

### `FlatfileSession`

- This class represents a session in the Flatfile platform.
- It stores information about the workspace, workbook, schema, uploads, and other session-related data.

### `EventCache`

- This class implements an event caching mechanism.
- It allows for caching and retrieval of event data based on cache keys.

### `EventHandler`

This class is an event handler implementation that extends the AuthenticatedClient class.

- It provides methods for registering event listeners, dispatching events, and managing child event handlers.
- It supports filtering events based on topic and context.
- It can be used to handle and process events in the Flatfile platform.

### `AuthenticatedClient`

This class is a base class for authenticated HTTP clients.

- It provides functionality for making authenticated HTTP requests using Axios.
- It handles access tokens, API URLs, and HTTP headers.

### Various utility functions and types:

`@flatfile/listener` includes utility functions and types related to event handling, filtering, and data manipulation.

These utilities support the functionality of the event handling and data processing components.

## Get Started

To get started with @flatfile/listener, follow our [Quickstart guide](https://flatfile.com/docs/quickstart/meet-the-workbook).