Add some helper functions to the Notion SDK (makenotion#320)

Author: wcauchois

ava.config.js

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+}

jest.config.js

@@ -27,7 +27,7 @@
     "build": "tsc",
     "prettier": "prettier --write .",
     "lint": "prettier --check . && eslint . --ext .ts && cspell '**/*' ",
-    "test": "ava",
+    "test": "jest ./test",
     "check-links": "git ls-files | grep md$ | xargs -n 1 markdown-link-check",
     "prebuild": "npm run clean",
     "clean": "rm -rf ./build",
@@ -44,14 +44,15 @@
     "node-fetch": "^2.6.1"
   },
   "devDependencies": {
-    "@ava/typescript": "^2.0.0",
+    "@types/jest": "^28.1.4",
     "@typescript-eslint/eslint-plugin": "^4.22.0",
     "@typescript-eslint/parser": "^4.22.0",
-    "ava": "^3.15.0",
     "cspell": "^5.4.1",
     "eslint": "^7.24.0",
+    "jest": "^28.1.2",
     "markdown-link-check": "^3.8.7",
     "prettier": "^2.3.0",
+    "ts-jest": "^28.0.5",
     "typescript": "^4.2.4"
   }
 }

package.json

@@ -11,7 +11,7 @@ import {
   isNotionClientError,
   RequestTimeoutError,
 } from "./errors"
-import { pick } from "./helpers"
+import { pick } from "./utils"
 import {
   GetBlockParameters,
   GetBlockResponse,

src/Client.ts

@@ -1,5 +1,5 @@
 import { SupportedResponse } from "./fetch-types"
-import { isObject } from "./helpers"
+import { isObject } from "./utils"
 import { Assert } from "./type-utils"
 
 /**

src/errors.ts

@@ -1,12 +1,12 @@
 /// <reference lib="dom" />
-import type { Assert, Await } from "./type-utils"
+import type { Assert } from "./type-utils"
 import type {
   RequestInit as NodeRequestInit,
   Response as NodeResponse,
 } from "node-fetch"
 
 type FetchFn = typeof fetch
-type FetchResponse = Await<ReturnType<FetchFn>>
+type FetchResponse = Awaited<ReturnType<FetchFn>>
 type RequestInfo = Parameters<FetchFn>[0]
 type RequestInit = NonNullable<Parameters<FetchFn>[1]>
 

src/fetch-types.ts

@@ -1,24 +1,120 @@
+import {
+  BlockObjectResponse,
+  DatabaseObjectResponse,
+  PageObjectResponse,
+  PartialBlockObjectResponse,
+  PartialDatabaseObjectResponse,
+  PartialPageObjectResponse,
+  PartialUserObjectResponse,
+  UserObjectResponse,
+} from "./api-endpoints"
+
+interface PaginatedArgs {
+  start_cursor?: string
+}
+
+interface PaginatedList<T> {
+  object: "list"
+  results: T[]
+  next_cursor: string | null
+  has_more: boolean
+}
+
+/**
+ * Returns an async iterator over the results of any paginated Notion API.
+ *
+ * Example (given a notion Client called `notion`):
+ *
+ * ```
+ * for await (const block of iteratePaginatedAPI(notion.blocks.children.list, {
+ *   block_id: parentBlockId,
+ * })) {
+ *   // Do something with block.
+ * }
+ * ```
+ *
+ * @param listFn A bound function on the Notion client that represents a conforming paginated
+ *   API. Example: `notion.blocks.children.list`.
+ * @param firstPageArgs Arguments that should be passed to the API on the first and subsequent
+ *   calls to the API. Any necessary `next_cursor` will be automatically populated by
+ *   this function. Example: `{ block_id: "<my block id>" }`
+ */
+export async function* iteratePaginatedAPI<Args extends PaginatedArgs, Item>(
+  listFn: (args: Args) => Promise<PaginatedList<Item>>,
+  firstPageArgs: Args
+): AsyncIterableIterator<Item> {
+  let nextCursor: string | null | undefined = firstPageArgs.start_cursor
+  do {
+    const response: PaginatedList<Item> = await listFn({
+      ...firstPageArgs,
+      start_cursor: nextCursor,
+    })
+    yield* response.results
+    nextCursor = response.next_cursor
+  } while (nextCursor)
+}
+
 /**
- * Utility for enforcing exhaustiveness checks in the type system.
+ * Collect all of the results of paginating an API into an in-memory array.
  *
- * @see https://basarat.gitbook.io/typescript/type-system/discriminated-unions#throw-in-exhaustive-checks
+ * Example (given a notion Client called `notion`):
  *
- * @param value The variable with no remaining values
+ * ```
+ * const blocks = collectPaginatedAPI(notion.blocks.children.list, {
+ *   block_id: parentBlockId,
+ * })
+ * // Do something with blocks.
+ * ```
+ *
+ * @param listFn A bound function on the Notion client that represents a conforming paginated
+ *   API. Example: `notion.blocks.children.list`.
+ * @param firstPageArgs Arguments that should be passed to the API on the first and subsequent
+ *   calls to the API. Any necessary `next_cursor` will be automatically populated by
+ *   this function. Example: `{ block_id: "<my block id>" }`
+ */
+export async function collectPaginatedAPI<Args extends PaginatedArgs, Item>(
+  listFn: (args: Args) => Promise<PaginatedList<Item>>,
+  firstPageArgs: Args
+): Promise<Item[]> {
+  const results: Item[] = []
+  for await (const item of iteratePaginatedAPI(listFn, firstPageArgs)) {
+    results.push(item)
+  }
+  return results
+}
+
+/**
+ * @returns `true` if `response` is a full `BlockObjectResponse`.
  */
-export function assertNever(value: never): never {
-  throw new Error(`Unexpected value should never occur: ${value}`)
+export function isFullBlock(
+  response: BlockObjectResponse | PartialBlockObjectResponse
+): response is BlockObjectResponse {
+  return "type" in response
 }
 
-type AllKeys<T> = T extends unknown ? keyof T : never
+/**
+ * @returns `true` if `response` is a full `PageObjectResponse`.
+ */
+export function isFullPage(
+  response: PageObjectResponse | PartialPageObjectResponse
+): response is PageObjectResponse {
+  return "url" in response
+}
 
-export function pick<O extends unknown, K extends AllKeys<O>>(
-  base: O,
-  keys: readonly K[]
-): Pick<O, K> {
-  const entries = keys.map(key => [key, base?.[key]])
-  return Object.fromEntries(entries)
+/**
+ * @returns `true` if `response` is a full `DatabaseObjectResponse`.
+ */
+export function isFullDatabase(
+  response: DatabaseObjectResponse | PartialDatabaseObjectResponse
+): response is DatabaseObjectResponse {
+  return "title" in response
 }
 
-export function isObject(o: unknown): o is Record<PropertyKey, unknown> {
-  return typeof o === "object" && o !== null
+/**
+ * @returns `true` if `response` is a full `UserObjectResponse`.
+ */
+export function isFullUser(
+  response: UserObjectResponse | PartialUserObjectResponse
+): response is UserObjectResponse {
+  return "type" in response
 }

src/helpers.ts

@@ -13,3 +13,11 @@ export {
   // Error helpers
   isNotionClientError,
 } from "./errors"
+export {
+  collectPaginatedAPI,
+  iteratePaginatedAPI,
+  isFullBlock,
+  isFullDatabase,
+  isFullPage,
+  isFullUser,
+} from "./helpers"

src/index.ts

@@ -1,4 +1,4 @@
-import { assertNever } from "./helpers"
+import { assertNever } from "./utils"
 
 export enum LogLevel {
   DEBUG = "debug",

src/logging.ts

@@ -2,15 +2,6 @@
  * Utilities for working with typescript types
  */
 
-/**
- * Unwrap the type of a promise
- */
-export type Await<T> = T extends {
-  then(onfulfilled?: (value: infer U) => unknown): unknown
-}
-  ? U
-  : T
-
 /**
  * Assert U is assignable to T.
  */

src/type-utils.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility for enforcing exhaustiveness checks in the type system.
+ *
+ * @see https://basarat.gitbook.io/typescript/type-system/discriminated-unions#throw-in-exhaustive-checks
+ *
+ * @param value The variable with no remaining values
+ */
+export function assertNever(value: never): never {
+  throw new Error(`Unexpected value should never occur: ${value}`)
+}
+
+type AllKeys<T> = T extends unknown ? keyof T : never
+
+export function pick<O extends unknown, K extends AllKeys<O>>(
+  base: O,
+  keys: readonly K[]
+): Pick<O, K> {
+  const entries = keys.map(key => [key, base?.[key]])
+  return Object.fromEntries(entries)
+}
+
+export function isObject(o: unknown): o is Record<PropertyKey, unknown> {
+  return typeof o === "object" && o !== null
+}

src/utils.ts

@@ -0,0 +1,7 @@
+import { Client } from "../src"
+
+describe("Notion SDK Client", () => {
+  it("Constructs without throwing", () => {
+    new Client({ auth: "foo" })
+  })
+})

test/Client.test.ts

@@ -0,0 +1,60 @@
+import { iteratePaginatedAPI } from "../src/helpers"
+
+describe("Notion API helpers", () => {
+  describe(iteratePaginatedAPI, () => {
+    const mockPaginatedEndpoint = jest.fn<
+      Promise<{
+        object: "list"
+        results: number[]
+        next_cursor: string | null
+        has_more: boolean
+      }>,
+      [{ start_cursor?: string }]
+    >()
+
+    beforeEach(() => {
+      mockPaginatedEndpoint.mockClear()
+    })
+
+    it("Paginates over two pages", async () => {
+      mockPaginatedEndpoint.mockImplementationOnce(async () => ({
+        object: "list",
+        results: [1, 2],
+        has_more: true,
+        next_cursor: "abc",
+      }))
+      mockPaginatedEndpoint.mockImplementationOnce(async () => ({
+        object: "list",
+        results: [3, 4],
+        has_more: false,
+        next_cursor: null,
+      }))
+      const results: number[] = []
+      for await (const item of iteratePaginatedAPI(mockPaginatedEndpoint, {})) {
+        results.push(item)
+      }
+      expect(results).toEqual([1, 2, 3, 4])
+      expect(mockPaginatedEndpoint).toHaveBeenCalledTimes(2)
+      expect(mockPaginatedEndpoint.mock.calls[0]?.[0].start_cursor).toBeFalsy()
+      expect(mockPaginatedEndpoint.mock.calls[1]?.[0].start_cursor).toEqual(
+        "abc"
+      )
+    })
+
+    it("Works when there's only one page", async () => {
+      mockPaginatedEndpoint.mockImplementationOnce(async () => ({
+        object: "list",
+        results: [1, 2],
+        has_more: false,
+        next_cursor: null,
+      }))
+      const results: number[] = []
+      for await (const item of iteratePaginatedAPI(mockPaginatedEndpoint, {})) {
+        results.push(item)
+      }
+      expect(results).toEqual([1, 2])
+      expect(mockPaginatedEndpoint).toHaveBeenCalledTimes(1)
+      expect(mockPaginatedEndpoint.mock.calls[0]?.[0].start_cursor).toBeFalsy()
+    })
+  })
+})