@protoutil/aip

TypeScript SDK for implementing Google API Improvement Proposals (AIP). Most of the utilities in this library are TypeScript re-implementations of the AIP Go library.

Install

This package has dependencies which require adding Buf as a registry in your package manager.

• For npm: npm config set @buf:registry https://buf.build/gen/npm/v1/ or add @buf:registry=https://buf.build/gen/npm/v1/ to your .npmrc
• For pnpm: pnpm config set @buf:registry https://buf.build/gen/npm/v1/
• For yarn: yarn config set npmScopes.buf.npmRegistryServer https://buf.build/gen/npm/v1/

See here for more information.

After adding Buf as a registry, install the package:

npm install @protoutil/aip

Sub-Modules

Each AIP is implemented as a separate sub-module with its own entry point:

Sub-Module	Import Path	AIP
Resource Names	@protoutil/aip/resourcename	AIP-122
Order By	@protoutil/aip/orderby	AIP-132
Resource Freshness (ETag)	@protoutil/aip/etag	AIP-154
Pagination	@protoutil/aip/pagination	AIP-158
Filtering	@protoutil/aip/filtering	AIP-160
Errors	@protoutil/aip/errors	AIP-193
Field Behavior	@protoutil/aip/fieldbehavior	AIP-203

Quick Examples

Parsing a filter string

import { parse, check, unparse } from "@protoutil/aip/filtering";

const parsed = parse('status = "active" AND rating > 3');
const { checkedExpr } = check(parsed);
const canonical = unparse(checkedExpr.expr!);

Pagination

import { parse } from "@protoutil/aip/pagination";

const pageToken = parse(RequestSchema, request);
const nextToken = pageToken.next(request.pageSize).toString();

Resource names

import { scan, matches } from "@protoutil/aip/resourcename";

const vars = scan("publishers/foo/books/bar", "publishers/{publisher}/books/{book}");
// { publisher: "foo", book: "bar" }

matches("shippers/{shipper}/sites/{site}", "shippers/1/sites/1"); // true

Error handling

import { NotFoundError } from "@protoutil/aip/errors";

throw new NotFoundError({
  message: "Book not found",
  errorInfo: { reason: "BOOK_NOT_FOUND", domain: "library.api" },
});