Add more complete types for the InternalModelManager

The InternalModelManager is public API for Gadget developers, so it should be well documented and have nice types for use inside the editor. We had `any`s everywhere when we can instead have nice types! This adds those.

Author: airhorns

packages/api-client-core/src/DataHydrator.ts

@@ -6,6 +6,7 @@ export const Hydrators = {
 
 export type Hydration = keyof typeof Hydrators;
 
+/** Instructions for a client to turn raw transport types (like strings) into useful client side types (like Dates). Unstable and not intended for developer use. */
 export interface HydrationPlan {
   [key: string]: Hydration;
 }

packages/api-client-core/src/GadgetRecordList.ts

@@ -4,12 +4,12 @@ import type { Jsonify } from "type-fest";
 import type { GadgetRecord, RecordShape } from "./GadgetRecord.js";
 import type { InternalModelManager } from "./InternalModelManager.js";
 import type { AnyModelManager } from "./ModelManager.js";
-import type { PaginationOptions } from "./operationBuilders.js";
 import { GadgetClientError, GadgetOperationError } from "./support.js";
+import { PaginateOptions } from "./types.js";
 
 type PaginationConfig = {
   pageInfo: { hasNextPage: boolean; hasPreviousPage: boolean; startCursor: string; endCursor: string };
-  options?: PaginationOptions;
+  options?: PaginateOptions;
 };
 
 /** Represents a list of objects returned from the API. Facilitates iterating and paginating. */

packages/api-client-core/src/InternalModelManager.ts

@@ -15,6 +15,7 @@ import {
   hydrateRecord,
   hydrateRecordArray,
 } from "./support.js";
+import type { InternalFieldSelection, InternalFindListOptions, InternalFindManyOptions, InternalFindOneOptions } from "./types";
 
 const internalErrorsDetails = `
 fragment InternalErrorsDetails on ExecutionError {
@@ -51,87 +52,6 @@ export const internalFindOneQuery = (apiIdentifier: string) => {
     `;
 };
 
-/**
- * A list of fields to select from the internal API
- * Matches the format of the Public API `select` option, but only allows going one level deep -- no relationships can be selected using the internal API.
- *
- * Supports passing a list of strings as a shorthand.
- *
- * @example
- * { fieldA: true, fieldB: true, fieldC: false }
- *
- * @example
- * ['fieldA', 'fieldB']
- */
-export type InternalFieldSelection = string[] | { [field: string]: boolean | null | undefined };
-
-/** Options for the api functions that return one record on an InternalModelManager */
-export interface InternalFindOneOptions {
-  /**
-   * What fields to retrieve from the API for this API call
-   **/
-  select?: InternalFieldSelection;
-}
-
-/** Options for functions that query a list of records on an InternalModelManager */
-export interface InternalFindListOptions {
-  /**
-   * A string to search for within all the stringlike fields of the records
-   * Matches the behavior of the Public API `search` option
-   **/
-  search?: string;
-  /**
-   * How to sort the returned records
-   * Matches the format and behavior of the Public API `sort` option
-   *
-   * @example
-   * {
-   *   sort: { publishedAt: "Descending" }
-   * }
-   **/
-  sort?: Record<string, "Ascending" | "Descending"> | Record<string, "Ascending" | "Descending">[];
-  /**
-   * Only return records matching this filter
-   * Matches the format and behavior of the Public API `filter` option
-   *
-   * @example
-   * {
-   *   filter: { published: { equals: true } }
-   * }
-   * */
-  filter?: Record<string, any>;
-  /**
-   * What fields to retrieve from the API for this API call
-   **/
-  select?: InternalFieldSelection;
-}
-
-/** Options for functions that return a paginated list of records from an InternalModelManager */
-export interface InternalFindManyOptions extends InternalFindListOptions {
-  /**
-   * A count of records to return
-   * Often used in tandem with the `after` option for GraphQL relay-style cursor pagination
-   * Matches the pagination style and behavior of the Public API
-   **/
-  first?: number;
-  /**
-   * The `after` cursor from the GraphQL Relay pagination spec
-   * Matches the pagination style and behavior of the Public API
-   **/
-  after?: string;
-  /**
-   * A count of records to return
-   * Often used in tandem with the `before` option for GraphQL relay-style cursor pagination
-   * Matches the pagination style and behavior of the Public API
-   **/
-  last?: number;
-  /**
-   * The `before` cursor from the GraphQL Relay pagination spec
-   * Matches the pagination style and behavior of the Public API
-   **/
-  before?: string;
-}
-
 const internalFindListVariables = (capitalizedApiIdentifier: string, options?: InternalFindListOptions) => {
   return {
     search: options?.search ? Var({ value: options?.search, type: "String" }) : undefined,

packages/api-client-core/src/operationBuilders.ts

@@ -2,7 +2,7 @@ import type { FieldSelection as BuilderFieldSelection, BuilderOperation, Variabl
 import { Call, Var, compileWithVariableValues } from "tiny-graphql-query-compiler";
 import type { FieldSelection } from "./FieldSelection.js";
 import { filterTypeName, sortTypeName } from "./support.js";
-import type { VariablesOptions } from "./types.js";
+import type { FindManyOptions, SelectionOptions, VariablesOptions } from "./types.js";
 
 const hydrationOptions = (modelApiIdentifier: string): BuilderFieldSelection => {
   return {
@@ -21,22 +21,7 @@ const fieldSelectionToQueryCompilerFields = (selection: FieldSelection, includeT
   return output;
 };
 
-type AnySort = any;
-type AnyFilter = any;
-
-export type SelectionOptions = { select?: any };
-
-export type PaginationOptions = {
-  sort?: AnySort | null;
-  filter?: AnyFilter | null;
-  search?: string | null;
-  after?: string | null;
-  first?: number | null;
-  before?: string | null;
-  last?: number | null;
-} & SelectionOptions;
-
-export type FindFirstPaginationOptions = Omit<PaginationOptions, "first" | "last" | "before" | "after">;
+export type FindFirstPaginationOptions = Omit<FindManyOptions, "first" | "last" | "before" | "after">;
 
 export const findOneOperation = (
   operation: string,
@@ -80,7 +65,7 @@ export const findManyOperation = (
   operation: string,
   defaultSelection: FieldSelection,
   modelApiIdentifier: string,
-  options?: PaginationOptions
+  options?: FindManyOptions
 ) => {
   return compileWithVariableValues({
     type: "query",

packages/api-client-core/src/operationRunners.ts

@@ -3,7 +3,6 @@ import type { GadgetConnection } from "./GadgetConnection.js";
 import type { GadgetRecord, RecordShape } from "./GadgetRecord.js";
 import { GadgetRecordList } from "./GadgetRecordList.js";
 import type { AnyModelManager } from "./ModelManager.js";
-import type { PaginationOptions, SelectionOptions } from "./operationBuilders.js";
 import {
   actionOperation,
   findManyOperation,
@@ -23,7 +22,7 @@ import {
   hydrateRecord,
   hydrateRecordArray,
 } from "./support.js";
-import type { VariablesOptions } from "./types.js";
+import type { FindManyOptions, SelectionOptions, VariablesOptions } from "./types.js";
 
 export const findOneRunner = async <Shape extends RecordShape = any>(
   modelManager: { connection: GadgetConnection },
@@ -67,7 +66,7 @@ export const findManyRunner = async <Shape extends RecordShape = any>(
   operation: string,
   defaultSelection: FieldSelection,
   modelApiIdentifier: string,
-  options?: PaginationOptions,
+  options?: FindManyOptions,
   throwOnEmptyData?: boolean
 ) => {
   const plan = findManyOperation(operation, defaultSelection, modelApiIdentifier, options);