fix(types): config options should not require what the library already defaults

docs/advanced/api.mdmodified+23-5

Changes to docs/advanced/api.md

		⋯6 linesShow the 6 lines above this hunk@@ -7,7 +7,7 @@ This page summarizes method signatures and brief descriptions. See feature pages
7	7	## Imports
8	8
9	9	```ts
10		-import type { CursorPaginationResult, DatabaseSchema, PaginationResult, QueryBuilderConfig, SchemaMeta, SortDirection, TransactionOptions, WhereExpression, WhereOperator } from 'bun-query-builder'
	10	+import type { CursorPaginationResult, DatabaseSchema, PaginationResult, QueryBuilderOptions, SchemaMeta, SortDirection, TransactionOptions, WhereExpression, WhereOperator } from 'bun-query-builder'
11	11	import {
12	12	// Schema and Model Definition
13	13	buildDatabaseSchema,
		⋯27 linesShow the 27 lines above this hunk@@ -41,10 +41,26 @@ const db = createQueryBuilder<typeof schema>({ schema, meta })
41	41
42	42	## Configuration
43	43
44		-- config: Global runtime config (merged via bunfig). Shape: `QueryBuilderConfig`
45		-- defaultConfig: Library defaults
	44	+- `defineConfig(options)`: identity helper for a typed `query-builder.config.ts`
	45	+- `setConfig(options)`: deep-merges `QueryBuilderOptions` into the live config
	46	+- `getConfig()`: loads `query-builder.config.ts` and `QUERY_BUILDER_*` env vars once, merges them in, returns the resolved config
	47	+- `config`: the live process-wide config, typed `QueryBuilderConfig` — every field is present, so `config.pagination.defaultPerPage` needs no guard
	48	+- `defaultConfig`: the library defaults, same resolved shape
46	49
47		-Key sections: `dialect`, `timestamps`, `pagination`, `aliasing`, `relations`, `transactionDefaults`, `sql`, `features`, `debug`.
	50	+Two types, two jobs. **Write** `QueryBuilderOptions`: every field optional at every
	51	+depth, so you supply only what you want to change. **Read** `QueryBuilderConfig`:
	52	+your options merged over the defaults, every field present. Annotating your own
	53	+config with the resolved type is what made every field added here a compile error
	54	+downstream ([#1062](https://github.com/stacksjs/bun-query-builder/issues/1062)).
	55	+
	56	+Key sections: `dialect`, `database`, `snapshotDir`, `migrationDir`, `timestamps`, `pagination`, `aliasing`, `relations`, `transactionDefaults`, `sql`, `features`, `softDeletes`, `hooks`, `debug`.
	57	+
	58	+Naming one leaf keeps the rest of its section:
	59	+
	60	+```ts
	61	+setConfig({ transactionDefaults: { retries: 5 } })
	62	+// retries is 5; sqlStates and backoff keep their defaults
	63	+```
48	64
49	65	## Schema & Models
50	66
		⋯225 linesShow the 225 lines above this hunk@@ -276,7 +292,9 @@ await db
276	292
277	293	- WhereOperator: '=', '!=', '<', '>', '<=', '>=', 'like', 'in', 'not in', 'is', 'is not'
278	294	- WhereExpression<TColumns>: object | tuple | raw
279		-- QueryBuilderConfig: see Configuration section
	295	+- QueryBuilderOptions: user-supplied configuration — every field optional, recursively. What you write in `query-builder.config.ts` or pass to `setConfig()`
	296	+- QueryBuilderConfig: defaults merged with your configuration — every field present. What `config`, `defaultConfig` and `getConfig()` give you
	297	+- DeepPartial&lt;T&gt;: the utility behind `QueryBuilderOptions`
280	298	- DatabaseSchema<ModelRecord>
281	299
282	300	---