@sanity/codegen 5.0.0-next.0-9b570ece82-202507150640 → 5.0.0-next.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 - 2024 Sanity.io
+Copyright (c) 2016 - 2025 Sanity.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/index.d.ts

@@ -1,12 +1,20 @@
 import {ExprNode} from 'groq-js'
 import {SchemaType} from 'groq-js'
+import * as t from '@babel/types'
 import {TransformOptions} from '@babel/core'
-import {TypeNode} from 'groq-js'
+import {WorkerChannel} from '@sanity/worker-channels'
+import {WorkerChannelReporter} from '@sanity/worker-channels'
 import * as z from 'zod'
 
-export declare type CodegenConfig = z.infer<typeof configDefintion>
+/**
+ * @deprecated use TypeGenConfig
+ */
+export declare type CodegenConfig = TypeGenConfig
 
-declare const configDefintion: z.ZodObject<
+/**
+ * @internal
+ */
+export declare const configDefinition: z.ZodObject<
   {
     path: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, 'many'>]>>
     schema: z.ZodDefault<z.ZodString>
@@ -32,6 +40,48 @@ declare const configDefintion: z.ZodObject<
   }
 >
 
+/**
+ * A module containing queries that have been evaluated.
+ * @public
+ */
+export declare interface EvaluatedModule {
+  filename: string
+  queries: EvaluatedQuery[]
+  errors: (QueryExtractionError | QueryEvaluationError)[]
+}
+
+/**
+ * An `ExtractedQuery` that has been evaluated against a schema, yielding a TypeScript type.
+ * @public
+ */
+export declare interface EvaluatedQuery extends ExtractedQuery {
+  id: t.Identifier
+  code: string
+  tsType: t.TSType
+  ast: t.ExportNamedDeclaration
+  stats: TypeEvaluationStats
+}
+
+/**
+ * A module (file) containing extracted GROQ queries.
+ * @public
+ */
+export declare interface ExtractedModule {
+  filename: string
+  queries: ExtractedQuery[]
+  errors: QueryExtractionError[]
+}
+
+/**
+ * A GROQ query extracted from a source file.
+ * @public
+ */
+export declare interface ExtractedQuery {
+  variable: QueryVariable
+  query: string
+  filename: string
+}
+
 /**
  * findQueriesInPath takes a path or array of paths and returns all GROQ queries in the files.
  * @param path - The path or array of paths to search for queries
@@ -45,11 +95,16 @@ export declare function findQueriesInPath({
   path,
   babelOptions,
   resolver,
-}: {
+}: FindQueriesInPathOptions): {
+  files: string[]
+  queries: AsyncIterable<ExtractedModule>
+}
+
+declare interface FindQueriesInPathOptions {
   path: string | string[]
   babelOptions?: TransformOptions
   resolver?: NodeJS.RequireResolve
-}): AsyncGenerator<ResultQueries | ResultError>
+}
 
 /**
  * findQueriesInSource takes a source string and returns all GROQ queries in it.
@@ -66,7 +121,16 @@ export declare function findQueriesInSource(
   filename: string,
   babelConfig?: TransformOptions,
   resolver?: NodeJS.RequireResolve,
-): NamedQueryResult[]
+): ExtractedModule
+
+export declare interface GenerateTypesOptions {
+  schema: SchemaType
+  schemaPath?: string
+  queries?: AsyncIterable<ExtractedModule>
+  root?: string
+  overloadClientMethods?: boolean
+  reporter?: WorkerChannelReporter<TypegenWorkerChannel>
+}
 
 /**
  * This is a custom implementation of require.resolve that takes into account the paths
@@ -78,34 +142,48 @@ export declare function findQueriesInSource(
 export declare function getResolver(cwd?: string): NodeJS.RequireResolve
 
 /**
- * NamedQueryResult is a result of a named query
+ * An error that occurred during query evaluation.
+ * @public
  */
-declare interface NamedQueryResult {
-  /** name is the name of the query */
-  name: string
-  /** result is a groq query */
-  result: resolveExpressionReturnType
-  /** location is the location of the query in the source */
-  location: {
-    start?: {
-      line: number
-      column: number
-      index: number
-    }
-    end?: {
-      line: number
-      column: number
-      index: number
-    }
-  }
+declare class QueryEvaluationError extends Error {
+  variable?: QueryVariable
+  filename: string
+  constructor({variable, cause, filename}: QueryEvaluationErrorOptions)
 }
 
-declare type QueryWithTypeNode = {
-  query: string
-  typeNode: TypeNode
+declare interface QueryEvaluationErrorOptions {
+  variable?: QueryVariable
+  cause: unknown
+  filename: string
 }
 
-export declare function readConfig(path: string): Promise<CodegenConfig>
+/**
+ * An error that occurred during query extraction.
+ * @public
+ */
+export declare class QueryExtractionError extends Error {
+  variable?: QueryVariable
+  filename: string
+  constructor({variable, cause, filename}: QueryExtractionErrorOptions)
+}
+
+declare interface QueryExtractionErrorOptions {
+  variable?: QueryVariable
+  cause: unknown
+  filename: string
+}
+
+declare interface QueryVariable {
+  id: t.Identifier
+  start?: number
+  end?: number
+}
+
+/**
+ * Read, parse and process a config file
+ * @internal
+ */
+export declare function readConfig(path: string): Promise<TypeGenConfig>
 
 /**
  * Read a schema from a given path
@@ -124,20 +202,6 @@ export declare function readSchema(path: string): Promise<SchemaType>
  */
 export declare function registerBabel(babelOptions?: TransformOptions): void
 
-declare type resolveExpressionReturnType = string
-
-declare type ResultError = {
-  type: 'error'
-  error: Error
-  filename: string
-}
-
-declare type ResultQueries = {
-  type: 'queries'
-  filename: string
-  queries: NamedQueryResult[]
-}
-
 /**
  * safeParseQuery parses a GROQ query string, but first attempts to extract any parameters used in slices. This method is _only_
  * intended for use in type generation where we don't actually execute the parsed AST on a dataset, and should not be used elsewhere.
@@ -145,60 +209,62 @@ declare type ResultQueries = {
  */
 export declare function safeParseQuery(query: string): ExprNode
 
+/**
+ * Statistics from the query type evaluation process.
+ * @public
+ */
+declare interface TypeEvaluationStats {
+  allTypes: number
+  unknownTypes: number
+  emptyUnions: number
+}
+
+export declare type TypeGenConfig = z.infer<typeof configDefinition>
+
 /**
  * A class used to generate TypeScript types from a given schema
- * @internal
  * @beta
  */
 export declare class TypeGenerator {
-  private generatedTypeName
-  private typeNameMap
-  private typeNodeNameMap
-  private readonly schema
-  constructor(schema: SchemaType)
-  /**
-   * Generate TypeScript types for the given schema
-   * @returns string
-   * @internal
-   * @beta
-   */
-  generateSchemaTypes(): string
-  /**
-   * Takes a identifier and a type node and generates a type alias for the type node.
-   * @param identifierName - The name of the type to generated
-   * @param typeNode - The type node to generate the type for
-   * @returns
-   * @internal
-   * @beta
-   */
-  generateTypeNodeTypes(identifierName: string, typeNode: TypeNode): string
-  static generateKnownTypes(): string
-  /**
-   * Takes a list of queries from the codebase and generates a type declaration
-   * for SanityClient to consume.
-   *
-   * Note: only types that have previously been generated with `generateTypeNodeTypes`
-   * will be included in the query map.
-   *
-   * @param queries - A list of queries to generate a type declaration for
-   * @returns
-   * @internal
-   * @beta
-   */
-  generateQueryMap(queries: QueryWithTypeNode[]): string
-  /**
-   * Since we are sanitizing identifiers we migt end up with collisions. Ie there might be a type mux.video and muxVideo, both these
-   * types would be sanityized into MuxVideo. To avoid this we keep track of the generated type names and add a index to the name.
-   * When we reference a type we also keep track of the original name so we can reference the correct type later.
-   */
-  private getTypeName
-  private getTypeNodeType
-  private generateArrayTsType
-  private generateObjectProperty
-  private generateObjectTsType
-  private generateInlineTsType
-  private generateUnionTsType
-  private generateDocumentType
+  private getInternalReferenceSymbolDeclaration
+  private getSchemaTypeGenerator
+  private getSchemaTypeDeclarations
+  private getAllSanitySchemaTypesDeclaration
+  private static getEvaluatedModules
+  private static getQueryMapDeclaration
+  generateTypes(options: GenerateTypesOptions): Promise<{
+    code: string
+    ast: t.Program
+  }>
 }
 
+export declare type TypegenWorkerChannel = WorkerChannel.Definition<{
+  generatedSchemaTypes: WorkerChannel.Event<{
+    internalReferenceSymbol: {
+      id: t.Identifier
+      code: string
+      ast: t.ExportNamedDeclaration
+    }
+    schemaTypeDeclarations: {
+      id: t.Identifier
+      name: string
+      code: string
+      tsType: t.TSType
+      ast: t.ExportNamedDeclaration
+    }[]
+    allSanitySchemaTypesDeclaration: {
+      code: string
+      id: t.Identifier
+      ast: t.ExportNamedDeclaration
+    }
+  }>
+  evaluatedModules: WorkerChannel.Stream<EvaluatedModule>
+  generatedQueryTypes: WorkerChannel.Event<{
+    queryMapDeclaration: {
+      code: string
+      ast: t.Program
+    }
+  }>
+}>
+
 export {}