first commit

docs/persistence/database/surrealdb/src/schema/discovery.md

@@ -0,0 +1,75 @@
+# discovery
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides file-system-based schema discovery for SurrealDB schema files (`.surql`, `.sql`). Schema discovery is the first step of the database initialisation workflow: given a directory path, `discoverSchemas` enumerates matching files, orders them according to `DEFAULT_SCHEMA_ORDER`, and returns typed `SchemaFile` descriptors. The `filterSchemas` and `getSchemasToLoad` helpers compose discovery with predicate filtering for conditional loading (e.g. skipping seed files in production).
+
+## Features
+
+- `getDefaultSchemaDir()` — returns conventional `./db/schema` path
+- `discoverSchemas()` — enumerates `.surql`/`.sql` files, optionally recursive
+- `sortSchemaFiles()` — orders files by `DEFAULT_SCHEMA_ORDER` then alphabetically
+- `filterSchemas()` — applies a `SchemaFilter` predicate to a file list
+- `getSchemasToLoad()` — discovery + filtering in one call
+- `readSchemaContent()` — reads file content with caching of pre-populated `content` field
+
+## Usage: Basic Example
+
+```ts
+import { discoverSchemas, readSchemaContent } from "@suaveplan/surrealdb/schema/discovery";
+
+const files = await discoverSchemas("./db/schema");
+for (const file of files) {
+  const content = await readSchemaContent(file);
+  console.log(file.name, content.length, "bytes");
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { getSchemasToLoad } from "@suaveplan/surrealdb/schema/discovery";
+
+const schemas = await getSchemasToLoad(
+  "./db/schema",
+  (f) => !f.name.includes("seed"), // skip seeds in production
+  { extensions: [".surql"], recursive: true }
+);
+```
+
+## API Reference
+
+### `getDefaultSchemaDir(): string`
+
+Returns `path.join(process.cwd(), "db", "schema")`.
+
+### `discoverSchemas(dir, options?): Promise<SchemaFile[]>`
+
+Reads `dir` for files with matching extensions. Returns sorted `SchemaFile[]`.
+
+**Throws:** `SurrealError(SURREAL.SCHEMA_LOAD_FAILED)` if directory read fails.
+
+### `sortSchemaFiles(files): SchemaFile[]`
+
+Pure. Orders by `DEFAULT_SCHEMA_ORDER` membership then lexicographically.
+
+### `filterSchemas(files, filter): SchemaFile[]`
+
+Pure. Returns `files.filter(filter)`.
+
+### `getSchemasToLoad(dir, filter?, options?): Promise<SchemaFile[]>`
+
+Combines `discoverSchemas` and `filterSchemas`.
+
+### `readSchemaContent(file): Promise<string>`
+
+Returns `file.content` if set, otherwise reads from `file.path`.
+
+**Throws:** `SurrealError(SURREAL.SCHEMA_LOAD_FAILED)` on read failure.
+
+## Implementation Notes
+
+Schema ordering uses `DEFAULT_SCHEMA_ORDER` from the constants module. Files matching known schema names (`"schema"`, `"tables"`, `"indexes"`, etc.) are placed first in that order; unrecognised names follow alphabetically. This matches the conventional SurrealDB schema application order where table definitions must precede index definitions.