Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(dart): derive reference sections from spec YAML section headers (#47994)

Lukas Klingsbo8c511032b694
diff --git a/apps/docs/scripts/generate-dart-reference.ts b/apps/docs/scripts/generate-dart-reference.ts
index d8119284727..df8c063e9c3 100644
--- a/apps/docs/scripts/generate-dart-reference.ts
+++ b/apps/docs/scripts/generate-dart-reference.ts
@@ -4,10 +4,14 @@
*
* Dart has no upstream TypeDoc output, so this script is the "pre-step" the
* reference README describes: it adapts the hand-authored legacy spec
- * (`spec/supabase_dart_v2.yml`) plus the shared section tree
- * (`spec/common-client-libs-sections.json`) into a TypeDoc-shaped JSON dump at
+ * (`spec/supabase_dart_v2.yml`) into a TypeDoc-shaped JSON dump at
* `spec/reference/dart/v2/supabase_flutter.json`.
*
+ * Each method's section comes from `category` / `subcategory` fields on its own
+ * YAML entry, so adding or moving a method only ever touches this one file. The
+ * `build-reference-content.ts` "barebone" step then generates the navigation
+ * tree from those tags — no separate section list to maintain.
+ *
* Each Dart method becomes a `variant: 'declaration'` node tagged with
* `@category` / `@subcategory` (so the build groups it into the right section)
* and carries the legacy function shape (description, notes, params, examples)
@@ -36,85 +40,54 @@ import { parse } from 'yaml'
const __dirname = dirname(fileURLToPath(import.meta.url))
const DOCS_DIR = join(__dirname, '..')
const YAML_PATH = join(DOCS_DIR, 'spec/supabase_dart_v2.yml')
-const SECTIONS_PATH = join(DOCS_DIR, 'spec/common-client-libs-sections.json')
const VERSION_DIR = join(DOCS_DIR, 'spec/reference/dart/v2')
const CONFIG_PATH = join(VERSION_DIR, 'config.json')
const OUT_PATH = join(VERSION_DIR, 'supabase_flutter.json')
-const LIB_ID = 'reference_dart_v2'
-
/**
- * Ids whose YAML entry is a category/subcategory overview rather than a method.
- * They are rendered through committed JSON partials (keyed by the subcategory
- * title slug), so they are skipped when building method declarations.
+ * Ids whose YAML entry is a section header rather than a method. Each header
+ * carries the `category` (and optional `subcategory`) that every method after
+ * it inherits, up to the next header. This is what lets individual methods omit
+ * section metadata entirely: authoring a new method just means placing it in the
+ * right section. Headers are skipped when building method declarations; their
+ * overview text is rendered from the committed JSON partials (keyed by the
+ * category/subcategory title slug).
+ *
+ * Listed in file order for readability.
*/
const HEADER_IDS = new Set([
- 'using-filters',
- 'using-modifiers',
+ 'auth-api',
'auth-mfa-api',
'passkey-api',
'admin-api',
'admin-passkey-api',
+ 'functions-api',
+ 'database-api',
+ 'realtime-api',
'file-buckets',
+ 'using-modifiers',
+ 'using-filters',
])
/** Top-level entries handled by markdown / top-level JSON partials, not methods. */
const SKIP_IDS = new Set(['introduction', 'installing', 'upgrade-guide', 'initializing'])
-/**
- * Dart-specific ids that are absent from the shared (JS-centric) section tree.
- * Map them to the category/subcategory they belong to.
- */
-const SECTION_OVERRIDE: Record<string, { category: string; subcategory: string | null }> = {
- 'max-affected': { category: 'Database', subcategory: 'Using modifiers' },
- 'link-identity-with-id-token': { category: 'Auth', subcategory: null },
- 'auth-reset-password-for-email': { category: 'Auth', subcategory: null },
-}
-
/** Method-name overrides for titles that don't yield a clean identifier. */
const NAME_OVERRIDE: Record<string, string> = {
explain: 'explain',
}
-interface SectionNode {
- id?: string
- title?: string
- type?: string
- excludes?: string[]
- items?: SectionNode[]
-}
-
interface DartFunction {
id: string
title: string
+ category?: string
+ subcategory?: string | null
description?: string
notes?: string
params?: unknown[]
examples?: unknown[]
}
-/** Walk the shared section tree, recording each id's category/subcategory for dart v2. */
-function buildSectionMap(
- sections: SectionNode[]
-): Map<string, { category: string; subcategory: string | null }> {
- const map = new Map<string, { category: string; subcategory: string | null }>()
- const included = (n: SectionNode) => !(n.excludes ?? []).includes(LIB_ID)
- const walk = (nodes: SectionNode[], category: string | null, subcategory: string | null) => {
- for (const node of nodes) {
- if (!included(node)) continue
- if (node.type === 'category') {
- walk(node.items ?? [], node.title ?? '', null)
- } else if (node.items && node.items.length) {
- walk(node.items, category, node.title ?? null)
- } else if (node.id) {
- map.set(node.id, { category: category ?? '', subcategory })
- }
- }
- }
- walk(sections, null, null)
- return map
-}
-
/**
* Derive a Dart method identifier from a legacy title:
* 'signUp()' -> 'signUp'
@@ -164,26 +137,53 @@ function slugify(value: string): string {
export async function generateDartReferenceDump(): Promise<{ methodCount: number }> {
const doc = parse(await readFile(YAML_PATH, 'utf-8')) as { functions: DartFunction[] }
- const sections = JSON.parse(await readFile(SECTIONS_PATH, 'utf-8')) as SectionNode[]
const config = JSON.parse(await readFile(CONFIG_PATH, 'utf-8')) as {
navigationPrefixes?: NavigationPrefixes
}
const navigationPrefixes = config.navigationPrefixes ?? {}
- const sectionMap = buildSectionMap(sections)
let nextId = 1
const children: unknown[] = []
const slugOwners = new Map<string, string>()
- const skipped: string[] = []
+ const orphaned: string[] = []
+
+ // The section a method belongs to is the one opened by the nearest preceding
+ // header entry. We walk the spec in order, updating the current section each
+ // time we hit a header, so methods themselves carry no section metadata.
+ let currentCategory: string | null = null
+ let currentSubcategory: string | null = null
for (const fn of doc.functions) {
- if (SKIP_IDS.has(fn.id) || HEADER_IDS.has(fn.id)) continue
+ if (SKIP_IDS.has(fn.id)) continue
+
+ if (HEADER_IDS.has(fn.id)) {
+ if (!fn.category) {
+ throw new Error(
+ `Dart converter: header "${fn.id}" needs a "category" field; it defines the ` +
+ `section that the methods after it inherit.`
+ )
+ }
+ currentCategory = fn.category
+ currentSubcategory = fn.subcategory ?? null
+ continue
+ }
- const section = SECTION_OVERRIDE[fn.id] ?? sectionMap.get(fn.id)
- if (!section) {
- skipped.push(fn.id)
+ // A method inherits the current section. It may still override either field
+ // independently: an explicit `subcategory` always wins, an explicit
+ // `category` (with no subcategory) starts a fresh, subcategory-less section,
+ // and anything left unset is inherited from the current header.
+ const category = fn.category ?? currentCategory
+ const subcategory =
+ fn.subcategory !== undefined
+ ? fn.subcategory
+ : fn.category !== undefined
+ ? null
+ : currentSubcategory
+ if (!category) {
+ orphaned.push(fn.id)
continue
}
+ const section = { category, subcategory }
const name = NAME_OVERRIDE[fn.id] ?? deriveName(fn.title)
if (!/^[A-Za-z][A-Za-z0-9]*$/.test(name)) {
@@ -229,10 +229,11 @@ export async function generateDartReferenceDump(): Promise<{ methodCount: number
await mkdir(dirname(OUT_PATH), { recursive: true })
await writeFile(OUT_PATH, JSON.stringify(dump, null, 2))
- if (skipped.length) {
+ if (orphaned.length) {
throw new Error(
- `Dart converter: ${skipped.length} ids have no section mapping (add them to ` +
- `common-client-libs-sections.json or SECTION_OVERRIDE): ${skipped.join(', ')}`
+ `Dart converter: ${orphaned.length} ids have no section (they appear before any ` +
+ `section header in supabase_dart_v2.yml). Move them under a header, add a header ` +
+ `before them, or list them in SKIP_IDS if they are not methods: ${orphaned.join(', ')}`
)
}
diff --git a/apps/docs/spec/supabase_dart_v2.yml b/apps/docs/spec/supabase_dart_v2.yml
index 66393e48d8f..67e2df89ca6 100644
--- a/apps/docs/spec/supabase_dart_v2.yml
+++ b/apps/docs/spec/supabase_dart_v2.yml
@@ -113,6 +113,9 @@ functions:
);
```
+ - id: auth-api
+ title: 'Auth'
+ category: Auth
- id: sign-up
title: 'signUp()'
description: |
@@ -1847,6 +1850,8 @@ functions:
```
- id: auth-mfa-api
title: 'Overview'
+ category: Auth
+ subcategory: Auth MFA
notes: |
This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the `supabase.auth.mfa` namespace.
@@ -2174,6 +2179,8 @@ functions:
```
- id: passkey-api
title: 'Auth Passkey'
+ category: Auth
+ subcategory: Auth Passkey
notes: |
This section contains methods for WebAuthn passkey registration, authentication, and management. Methods are invoked behind the `supabase.auth.passkey` namespace.
@@ -2330,6 +2337,8 @@ functions:
```
- id: admin-api
title: 'Overview'
+ category: Auth
+ subcategory: Auth Admin
notes: |
- Any method under the `supabase.auth.admin` namespace requires a `secret` key.
- These methods are considered admin methods and should be called on a trusted server. Never expose your `secret` key in the Flutter app.
@@ -2828,6 +2837,8 @@ functions:
```
- id: admin-passkey-api
title: 'Passkey Admin API'
+ category: Auth
+ subcategory: Passkey Admin
notes: |
Contains passkey administration methods, accessed under the `supabase.auth.admin.passkey` namespace. Requires a `secret` key.
@@ -2875,6 +2886,9 @@ functions:
passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
);
```
+ - id: functions-api
+ title: 'Edge Functions'
+ category: Edge Functions
- id: invoke
title: 'invoke()'
description: |
@@ -2923,6 +2937,9 @@ functions:
},
);
```
+ - id: database-api
+ title: 'Database'
+ category: Database
- id: select
description: |
Perform a SELECT query on the table or view.
@@ -3929,6 +3946,9 @@ functions:
Postgres functions that return tables can also be combined with [Filters](/docs/reference/dart/using-filters) and [Modifiers](/docs/reference/dart/using-modifiers).
hideCodeBlock: true
+ - id: realtime-api
+ title: 'Realtime'
+ category: Realtime
- id: subscribe
description: |
Subscribe to realtime changes in your database.
@@ -4211,6 +4231,8 @@ functions:
```
- id: file-buckets
title: 'Overview'
+ category: Storage
+ subcategory: File Buckets
notes: |
This section contains methods for working with File Buckets.
# - id: analytics-buckets
@@ -5053,6 +5075,8 @@ functions:
```
- id: using-modifiers
title: Using Modifiers
+ category: Database
+ subcategory: Using modifiers
description: |
Filters work on the row level. That is, they allow you to return rows that
only match certain conditions without changing the shape of the rows.
@@ -5671,6 +5695,8 @@ functions:
isSpotlight: false
- id: using-filters
title: Using Filters
+ category: Database
+ subcategory: Using filters
description: |
Filters allow you to only return rows that match certain conditions.