feat: display params for ref functions

supabase · charislam · Aug 13, 2024 · Jul 4, 2024 · Jul 4, 2024 · Jul 5, 2024
commit b1147916973243ef81e36b9cfdc3db7875b0e68a
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx
@@ -203,7  203,7 @@ const menus: Menu[] = [
   },
 ]
 
-export function getMenuById(id: MenuId) {
 function getMenuById(id: MenuId) {
   return menus.find((menu) => menu.id === id)
 }
 

diff --git a/apps/docs/features/docs/Reference.sdkPage.tsx b/apps/docs/features/docs/Reference.sdkPage.tsx
@@ -39,8  39,8 @@ function ClientSdkReferencePage({
       }
     >
       <LayoutMainContent>
-        <article>
-          <ClientLibHeader menuData={menuData} className="mb-8" />
         <article className="@container/article">
           <ClientLibHeader menuData={menuData} className="mt-4 mb-8" />
           <ClientLibIntroduction libPath={libPath} excludeName={libId} />
           <ClientLibRefSections
             libPath={libPath}

diff --git a/apps/docs/features/docs/Reference.sections.tsx b/apps/docs/features/docs/Reference.sections.tsx
@@ -1,13  1,16 @@
-import type { AbbrevCommonClientLibSection } from '~/features/docs/Reference.utils'
-import type { MethodTypes } from '~/features/docs/Reference.typeSpec'
-
 import { Fragment } from 'react'
 
 import { getRefMarkdown, MDXRemoteRefs } from '~/features/docs/Reference.mdx'
 import type { MethodTypes } from '~/features/docs/Reference.typeSpec'
 import { getTypeSpec } from '~/features/docs/Reference.typeSpec'
-import { RefSubLayout } from '~/features/docs/Reference.ui'
 import { FnParameterDetails, RefSubLayout } from '~/features/docs/Reference.ui'
 import { StickyHeader } from './Reference.ui.client'
-import { genClientSdkSectionTree, getSpecFnsCached } from '~/features/docs/Reference.utils'
 import type { AbbrevCommonClientLibSection } from '~/features/docs/Reference.utils'
 import {
   genClientSdkSectionTree,
   getSpecFnsCached,
   normalizeMarkdown,
 } from '~/features/docs/Reference.utils'
 
 interface ClientLibRefSectionsProps {
   libPath: string
@@ -137,11  140,39 @@ async function FunctionSection({ link, section, specFile, useTypeSpec }: Functio
     types = await getTypeSpec(fn['$ref'] as string)
   }
 
   const fullDescription = [
     types?.comment?.shortText,
     'description' in fn && (fn.description as string),
     'notes' in fn && (fn.notes as string),
   ]
     .filter(Boolean)
     .map(normalizeMarkdown)
     .join('\n\n')
 
   return (
-    <RefSubLayout.Section {...section}>
-      <StickyHeader {...section} link={link} scrollSpyHeader />
-      <pre>{JSON.stringify(fn, null, 2)}</pre>
-      <pre>{JSON.stringify(types, null, 2)}</pre>
     <RefSubLayout.Section columns="double" {...section}>
       <StickyHeader {...section} link={link} scrollSpyHeader className="col-[1_/_-1]" />
       <div className="overflow-hidden flex flex-col gap-8">
         <div className="prose break-words text-sm">
           <MDXRemoteRefs source={fullDescription} />
         </div>
         <FnParameterDetails
           parameters={
             'overwriteParams' in fn
               ? (fn.overwriteParams as Array<object>).map((overwrittenParams) => ({
                   ...overwrittenParams,
                   __overwritten: true,
                 }))
               : types?.params
           }
           altParameters={types?.altSignatures?.map(({ params }) => params)}
           className="max-w-[80ch]"
         />
         <pre className="text-sm">{JSON.stringify(fn, null, 2)}</pre>
       </div>
       <div className="overflow-hidden">
         <pre className="text-sm">{JSON.stringify(types, null, 2)}</pre>
       </div>
     </RefSubLayout.Section>
   )
 }

diff --git a/apps/docs/features/docs/Reference.typeSpec.ts b/apps/docs/features/docs/Reference.typeSpec.ts
@@ -37,27  37,33 @@ interface ModuleTypes {
 export interface MethodTypes {
   name: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  params: Array<ParamType>
   params: Array<FunctionParameterType>
   ret: ReturnType | undefined
   altSignatures?: [
     {
       params: Array<FunctionParameterType>
       ret: ReturnType | undefined
     },
   ]
 }
 
 interface Comment {
   shortText?: string
   text?: string
 }
 
-interface ParamType {
 export interface FunctionParameterType {
   name: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
   isOptional?: boolean
-  type: Type | undefined
   type: TypeDetails | undefined
 }
 
 interface ReturnType {
-  type: Type | undefined
   type: TypeDetails | undefined
 }
 
-type Type = IntrinsicType | LiteralType | CustomType
 export type TypeDetails = IntrinsicType | LiteralType | CustomType
 
 /**
  * Type definition for an intrinsic (built-in) TypeScript type, for example,
@@ -91,65  97,65 @@ interface NameOnlyType {
 }
 
 interface CustomObjectType {
-  type: 'customObject'
   type: 'object'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  properties: Array<PropertyType>
   properties: Array<CustomTypePropertyType>
 }
 
-interface CustomUnionType {
-  type: 'customUnion'
 export interface CustomUnionType {
   type: 'union'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  subTypes: Array<Type>
   subTypes: Array<TypeDetails>
 }
 
 interface CustomFunctionType {
   type: 'function'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  params: Array<ParamType>
   params: Array<FunctionParameterType>
   ret: ReturnType | undefined
 }
 
 interface ArrayType {
   type: 'array'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  elemType: Type | undefined
   elemType: TypeDetails | undefined
 }
 
 interface RecordType {
   type: 'record'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  keyType: Type | undefined
-  valueType: Type | undefined
   keyType: TypeDetails | undefined
   valueType: TypeDetails | undefined
 }
 
 interface IndexSignatureType {
   type: 'index signature'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  keyType: Type | undefined
-  valueType: Type | undefined
   keyType: TypeDetails | undefined
   valueType: TypeDetails | undefined
 }
 
 interface PromiseType {
   type: 'promise'
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
-  awaited: Type | undefined
   awaited: TypeDetails | undefined
 }
 
 /**
  * Type definition for a property on a custom type definition.
  */
-interface PropertyType {
 export interface CustomTypePropertyType {
   name?: string | typeof TYPESPEC_NODE_ANONYMOUS
   comment?: Comment
   isOptional?: boolean
-  type: Type | undefined
   type: TypeDetails | undefined
 }
 
 // The following is the API of this module, and the only externally exposed
@@ -316,17  322,23 @@ function parseMethod(
     comment,
   }
 
   if (node.signatures.length > 1) {
     types.altSignatures = node.signatures
       .slice(1)
       .map((signature) => parseSignature(signature, map))
   }
 
   res.methods.set($ref, types)
 }
 
 function parseSignature(
   signature: any,
   map: Map<number, any>
-): { params: Array<ParamType>; ret: ReturnType; comment?: Comment } {
-  const params: Array<ParamType> = (signature.parameters ?? []).map((param: any) => {
 ): { params: Array<FunctionParameterType>; ret: ReturnType; comment?: Comment } {
   const params: Array<FunctionParameterType> = (signature.parameters ?? []).map((param: any) => {
     const type = parseType(param.type, map)
 
-    const res: ParamType = {
     const res: FunctionParameterType = {
       name: nameOrAnonymous(param),
       type,
     }
@@ -447,6  459,10 @@ function parseReferenceType(type: any, map: Map<number, any>) {
     return parsePromiseType(type, map)
   }
 
   if (type.package === 'typescript' && type.qualifiedName === 'Extract') {
     return parseExtractType(type, map)
   }
 
   if (type.package && type.qualifiedName) {
     return {
       type: 'nameOnly',
@@ -500,7  516,7 @@ function parseUnionType(type: any, map: Map<number, any>): CustomUnionType {
   const subTypes = type.types.filter(Boolean).map((type) => parseType(type, map))
 
   return {
-    type: 'customUnion',
     type: 'union',
     name: nameOrAnonymous(type),
     subTypes,
   }
@@ -525,10  541,15 @@ function parsePromiseType(type: any, map: Map<number, any>): PromiseType {
   }
 }
 
 function parseExtractType(type: any, map: Map<number, any>): CustomUnionType {
   const extractedUnion = parseUnionType(type.typeArguments[1], map)
   return extractedUnion
 }
 
 function parseReflectionType(type: any, map: Map<number, any>) {
   if (!type.declaration) return undefined
 
-  let res: Type
   let res: TypeDetails
   switch (type.declaration.kindString) {
     case 'Type literal':
       res = parseTypeLiteral(type, map)
@@ -540,14  561,14 @@ function parseReflectionType(type: any, map: Map<number, any>) {
   return res
 }
 
-function parseTypeLiteral(type: any, map: Map<number, any>): Type {
 function parseTypeLiteral(type: any, map: Map<number, any>): TypeDetails {
   const name = nameOrAnonymous(type)
 
   if ('children' in type.declaration) {
     const properties = type.declaration.children.map((child: any) => parseTypeInternals(child, map))
     return {
       name,
-      type: 'customObject',
       type: 'object',
       properties,
     } satisfies CustomObjectType
   }
@@ -582,7  603,7 @@ function parseTypeLiteral(type: any, map: Map<number, any>): Type {
 function parseIndexedAccessType(type: any, map: Map<number, any>) {
   return {
     type: 'nameOnly',
-    name: `${type.objectType?.name ?? ''}[${type.indexType.value ?? type.indexType.name ?? ''}]`,
     name: `${type.objectType?.name ?? ''}['${type.indexType.value ?? type.indexType.name ?? ''}']`,
   }
 }
 
@@ -599,7  620,7 @@ function parseInterface(type: any, map: Map<number, any>): CustomObjectType {
   const properties = (type.children ?? []).map((child) => parseTypeInternals(child, map))
 
   return {
-    type: 'customObject',
     type: 'object',
     name: nameOrAnonymous(type),
     properties,
   }
@@ -641,7  662,7 @@ function parseInternalProperty(elem: any, map: Map<number, any>) {
   const res = {
     name,
     type,
-  } as PropertyType
   } as CustomTypePropertyType
 
   if (elem.flags?.isOptional) {
     res.isOptional = true

diff --git a/apps/docs/features/docs/Reference.ui.client.tsx b/apps/docs/features/docs/Reference.ui.client.tsx
@@ -12,6  12,7 @@ interface StickyHeaderProps {
    */
   link?: string
   monoFont?: boolean
   className?: string
   /**
    * Whether the header updates the URL on scroll
    */
@@ -27,13  28,14 @@ function StickyHeader({
   slug,
   link,
   monoFont = false,
   className,
   scrollSpyHeader = false,
   crawlerPage = false,
 }: StickyHeaderProps) {
   const { ref } = useInView({
     threshold: 1,
     rootMargin: '0% 0% -50% 0%',
-    onChange: (inView, entry) => {
     onChange: (inView) => {
       if (inView && scrollSpyHeader) {
         window.history.replaceState(null, '', link)
       }
@@ -53,7  55,8 @@ function StickyHeader({
             'text-2xl font-medium text-foreground',
             'mt-0',
             'scroll-mt-[calc(33px 2rem)] lg:scroll-mt-[calc(var(--header-height) 1px 4rem)]',
-            monoFont && 'font-mono'
             monoFont && 'font-mono',
             className
           )}
         >
           {title}