first commit

docs/identity/auth/better-auth-surrealdb/src/schemas/link-fields.md

@@ -0,0 +1,75 @@
+# schemas/link-fields
+
+## Purpose
+
+Zod boundary schema asserting the structural shape of a `LinkFieldMap`. Used
+to validate the optional `linkFields` argument passed to
+`createBetterAuthSurrealAdapter` and to gate any callers that hand-roll their
+own override map at runtime. Validation rejects non-string targets, empty
+keys, and identifiers that would break the generated SurrealQL identifier
+rule (`/^[a-zA-Z_][a-zA-Z0-9_]*$/`).
+
+## Features
+
+- Identifier-rule enforcement on model name, field name, and target table.
+- Empty-string rejection (model/field/target must be `min(1)`).
+- Composable: re-exported as `LinkFieldMapSchema` from `./schemas` and
+  embedded inside `BetterAuthSurrealAdapterOptionsSchema`.
+- Type-level `LinkFieldMapSchemaInput` / `LinkFieldMapSchemaOutput` exports
+  for downstream consumers that derive their own option shapes.
+
+## Usage: Basic
+
+```ts
+import { LinkFieldMapSchema } from "@suaveplan/better-auth-surrealdb/schemas/link-fields";
+
+const parsed = LinkFieldMapSchema.safeParse({
+    session: { userId: "user" },
+});
+if (!parsed.success) throw parsed.error;
+```
+
+## Usage: Advanced
+
+```ts
+import { LinkFieldMapSchema } from "@suaveplan/better-auth-surrealdb/schemas/link-fields";
+
+// Reject non-string targets at the wire boundary
+const bad = LinkFieldMapSchema.safeParse({
+    session: { userId: 5 },
+});
+console.log(bad.success); // false
+
+// Custom map merging
+const merged = LinkFieldMapSchema.parse({
+    ...{ session: { userId: "user" } },
+    ...{ api_key: { userId: "user" } },
+});
+```
+
+## API Reference
+
+- `LinkFieldMapSchema: z.ZodType` — accepts `Record<string, Record<string, string>>`.
+- `LinkFieldMapSchemaInput` — pre-parse type.
+- `LinkFieldMapSchemaOutput` — post-parse type.
+
+## Implementation Notes
+
+The schema uses `z.record(IdentString, z.record(IdentString, IdentString))`.
+Keys go through Zod's `z.record(keySchema, valueSchema)` 4-arg form so the
+identifier check applies to the model/field names as well as the target
+table. Empty-object inputs (`{}`) parse successfully — operators commonly
+pass `linkFields: {}` to disable prefix manipulation entirely.
+
+The `IdentString` schema delegates to `z.string().min(1).regex(...)` so
+the inner regex never has to deal with empty strings (which would slip
+through the regex via the implicit anchored-success path). The error
+message attached to the regex check is human-readable and surfaces in
+`ZodError.issues[i].message` for downstream error reporters, while the
+issue path lets log aggregators pivot on offending fields without
+parsing the message.
+
+Type-level exports `LinkFieldMapSchemaInput` and `LinkFieldMapSchemaOutput`
+are identical in this case (the schema is `transform`-free) but the
+distinction is preserved so future extensions (e.g. coercing aliases to
+canonical table names) can change one without breaking the other.