npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@qualifyze/airtable

v2.0.2

Published

A more powerful airtable client

Downloads

812

Readme

@qualifyze/airtable

What is @qualifyze/airtable?

A more powerful JS/TS client for the Airtable API that can be used with Airtable's API directly or through proxy-endpoints that provide a different Auth mechanism.

Why is @qualifyze/airtable useful?

In comparison to the official client, @qualifyze/airtable brings these advantages:

  • You can use this client to connect multiple API endpoints.
  • You can use this client to connect to Airtable API endpoints with an alternative auth-mechanism.
  • Allows type-annotations and run-time validations for table-fields.
  • Pagination when listing records is much easier through Async Iterators.
  • Allows the use of Array Notation when filtering queries through @qualifyze/airtable-formulator.

How to use it?

The API of this client for the most part is identical to the official clients API.

Connect to the official API using the official client

import Airtable from "airtable";
import { Base } from "@qualifyze/airtable";

Airtable.configure({ apiKey: "YOUR_SECRET_API_KEY" });
const officialClient = new Airtable();

const base = Base.fromOfficialClient(officialClient, myBaseId);

Use Type Annotation for table fields

type Person = {
  name?: string;
  age?: number;
};

const persons = base.table<Person>("persons");

const record = persons.create({
  name: "Eve",
  age: "not a number", // Type Error
});

Add run-time validators

With the Validator interface you can wrap any validation library to validate your data at runtime.

import { Validator } from "./validator";

const validator: Validator<Person> = {
  createValidator(reference?: string) {
    return {
      isValid(data: unknown): data is Person {
        // Return true if data is a person.
      },
      getValidationError(): Error | null {
        // Return validation errors that were encountered in the last call to isValid().
        // Include reference to easily identify the invalid record.
      },
    };
  },
};

const persons = base.table("persons", validator);

Iterating over list results

const query = {
  filterByFormula: [">", { field: "age" }, 35],
};

for await (const person of persons.select(query)) {
  console.log(person.data);
}

As with any Async iterators it has to be warned that an iterator can only be used once at a time:


async function runIteration(query) {
    for await(const record of query) {
        // Do something.
    }
}

// BAD: Use same same query in parallel iterators.
const query = table.query({});
Promise.all(runIteration(query), runIteration(query)); // <- BAD

// GOOD: For parallel iterations use separate query obejcts.
const queryA = table.query({});
const queryB = table.query({});
Promise.all(runIteration(queryA), runIteration(queryB)); // <- GOOD

Use an alternative Authentication Method, rather than the official client

import { Base, Endpoint, ActionPayload, RestMethod } from "@qualifyze/airtable";

const myClient: Endpoint = {
  async runAction(
    method: RestMethod,
    { path, payload: { query, body } }: ActionPayload
  ): Promise<unknown> {
    // Implement your own Endpoint interface that
    // Throw any API-level errors.
    // Return the response payload as is.
  },
};

const base = new Base(myClient);

Key API incompatibilities to the official client

No Callback APIs

It's 2022. Why would you need callback APIs?

Use Promises or async/await.

Record objects are Immutable:

So it won't drive you insane.

const record = persons.find("my-id");
const updatedRecord = await record.update({ age: record.data.age + 1 });

console.log({
  before: record.data.age,
  after: updatedRecord.data.age
});

There are no .set() or .get() methods on the Record API.

Testing changes

In addition to usual lint and test scripts, there is an integration test to check the client against the real airtable base.

  • create the file .env based on .env.example
  • pick a table with at least two string fields where it's ok to create new records
  • bash npm run integration

All the created records are deleted in case of the successful execution.

Contributing code

Add the changeset description using the interactive command npx changeset. This will create a new file in .changeset folder which defines how the change should affect the package version (major, minor, patch) and contains a small description for the release notes. The file should be part of the same pull requests it describes.

Release a new version

Each PR with changeset files merged into the main branch will open/update PR to release the package with the proper version. Merging that PR will bump the version, create a GitHub release and publish the new version to the npm registry.

Unfortunately, the test workflow required to merge a PR is not triggered by the version PR. The workaround is assigning PR to yourself which is added as an additional trigger for the test workflow.