Add config helper, typings, example config, and README

Expose a typed config API and improve docs/workflow. Adds defineConfig runtime helper (src/config-public.js) and TypeScript declarations (src/config.d.ts), an example jsondb.config.example.mjs, and updates package exports to expose jsondb/config. Update default mock.delay in src/config.js to [30,100]. Rework README (renamed to jsondb) to document defaults, CLI usage, REST-first workflow, and config details. Update tests and helpers to support the new "jsondb" package alias, add tests for mock delay and config usage, and fix internal imports to use the jsondb entrypoints. This change centralizes configuration ergonomics and clarifies defaults and developer UX.

Author: PatrickJS

README.md

@@ -0,0 +1,51 @@
+// @ts-check
+import { defineConfig } from 'jsondb/config';
+
+export default defineConfig({
+  // Fixture source folder. Defaults to './db'.
+  dbDir: './db',
+
+  // Runtime output folder. Defaults to './.jsondb'.
+  stateDir: './.jsondb',
+
+  // mirror: keep source fixtures unchanged and write app edits to .jsondb/state.
+  // source: write generated ids back to plain .json fixtures when needed.
+  mode: 'mirror',
+
+  // Generated TypeScript types. The default outFile is gitignored; commitOutFile
+  // is useful when app code imports generated types in CI or fresh checkouts.
+  types: {
+    enabled: true,
+    outFile: './.jsondb/types/index.ts',
+    commitOutFile: null,
+    useReadonly: false,
+    emitComments: true,
+  },
+
+  // Default local development behavior is permissive: unknown schema-backed
+  // fields warn. Use 'error' when you want schema drift to fail sync/writes.
+  schema: {
+    unknownFields: 'warn',
+  },
+
+  // Optional schema-only mock records. Leave off when real fixture data exists.
+  seed: {
+    generateFromSchema: false,
+    generatedCount: 5,
+  },
+
+  // Local server settings.
+  server: {
+    host: '127.0.0.1',
+    port: 7331,
+    maxBodyBytes: 1048576,
+  },
+
+  // Local latency is on by default so loading states are visible. Use 0 to
+  // disable delay, 50 for a fixed 50ms delay, or [50, 300] for a range.
+  // Random errors are off by default.
+  mock: {
+    delay: [30, 100],
+    errors: null,
+  },
+});

jsondb.config.example.mjs

@@ -15,6 +15,10 @@
       "types": "./src/schema.d.ts",
       "default": "./src/schema-builders.js"
     },
+    "./config": {
+      "types": "./src/config.d.ts",
+      "default": "./src/config-public.js"
+    },
     "./client": {
       "types": "./src/index.d.ts",
       "default": "./src/client.js"
@@ -37,6 +41,7 @@
     "examples/*/db/**",
     "examples/*/jsondb.config.mjs",
     "examples/*/src/generated/**",
+    "jsondb.config.example.mjs",
     "README.md",
     "SPEC.md"
   ],

package.json

@@ -0,0 +1,3 @@
+export function defineConfig(config) {
+  return config;
+}

src/config-public.js

@@ -0,0 +1,24 @@
+import type { JsonDbOptions } from './index.d.ts';
+
+/**
+ * jsondb project configuration.
+ *
+ * Use with `// @ts-check` in `jsondb.config.mjs` for editor autocomplete:
+ *
+ * ```js
+ * import { defineConfig } from 'jsondb/config';
+ *
+ * export default defineConfig({
+ *   dbDir: './db',
+ * });
+ * ```
+ */
+export type JsonDbConfig = JsonDbOptions;
+
+/**
+ * Type-only helper for authoring `jsondb.config.mjs`.
+ *
+ * It returns the config unchanged at runtime and exists so JavaScript config
+ * files get autocomplete, literal value checking, and inline JSDoc.
+ */
+export function defineConfig<Config extends JsonDbConfig>(config: Config): Config;

src/config.d.ts

@@ -46,7 +46,7 @@ export const DEFAULT_CONFIG = {
     path: '/graphql',
   },
   mock: {
-    delay: null,
+    delay: [30, 100],
     errors: null,
   },
   generate: {

src/config.js

@@ -4,58 +4,91 @@ export type JsonDbTypeMap = {
 };
 
 export type JsonDbOptions = {
+  /** Project root used to resolve relative config paths. Defaults to process.cwd(). */
   cwd?: string;
+  /** Explicit config file path. Defaults to jsondb.config.mjs/js lookup from cwd. */
   configPath?: string;
+  /** Fixture source folder. Defaults to "./db". */
   dbDir?: string;
+  /** Backwards-compatible fixture source folder alias. If set, it wins over dbDir. */
   sourceDir?: string;
+  /** Generated runtime output folder. Defaults to "./.jsondb". */
   stateDir?: string;
+  /** "mirror" keeps source fixtures unchanged; "source" may write generated ids back to plain .json fixtures. */
   mode?: 'mirror' | 'source';
+  /** Run sync automatically when opening the package API. */
   syncOnOpen?: boolean;
+  /** Keep valid resources available when one source file has diagnostics. */
   allowSourceErrors?: boolean;
   types?: {
+    /** Generate TypeScript types during sync. */
     enabled?: boolean;
+    /** Gitignored generated type output. Defaults to "./.jsondb/types/index.ts". */
     outFile?: string;
+    /** Optional committed copy for app/CI imports. */
     commitOutFile?: string | null;
+    /** Emit readonly object properties in generated types. */
     useReadonly?: boolean;
+    /** Emit JSDoc from schema field descriptions. */
     emitComments?: boolean;
+    /** Export JsonDbCollections, JsonDbDocuments, and JsonDbTypes helpers. */
     exportRuntimeHelpers?: boolean;
   };
   schema?: {
+    /** Which inputs define schemas. "auto" uses schema files when present and otherwise infers from data. */
     source?: 'auto' | 'data' | 'schema';
+    /** Allow JSONC source files. */
     allowJsonc?: boolean;
+    /** How schema-backed resources handle fields not declared by schema. */
     unknownFields?: 'allow' | 'warn' | 'error';
+    /** Future migration policy for safe additive changes. */
     additiveChanges?: 'auto' | 'manual';
+    /** Future migration policy for destructive changes. */
     destructiveChanges?: 'manual';
+    /** Future migration policy for field type changes. */
     typeChanges?: 'manual';
   };
   defaults?: {
+    /** Apply schema defaults on create through package, REST, and GraphQL writes. */
     applyOnCreate?: boolean;
+    /** Apply defaults during safe additive mirror sync. */
     applyOnSafeMigration?: boolean;
   };
   seed?: {
+    /** Generate mock runtime rows for schema-only resources with empty seed data. */
     generateFromSchema?: boolean;
+    /** Number of mock rows to generate when generateFromSchema is true. */
     generatedCount?: number;
   };
+  /** Per-collection overrides such as custom id field names. */
   collections?: Record<string, { idField?: string }>;
   server?: {
+    /** Local HTTP host. Defaults to "127.0.0.1". */
     host?: string;
+    /** Local HTTP port. Defaults to 7331. */
     port?: number;
+    /** Maximum JSON request body size in bytes. Defaults to 1048576. */
     maxBodyBytes?: number;
   };
   rest?: {
+    /** Enable generated REST routes. */
     enabled?: boolean;
   };
   graphql?: {
+    /** Enable the focused dependency-free GraphQL endpoint. */
     enabled?: boolean;
+    /** GraphQL HTTP path. Defaults to "/graphql". */
     path?: string;
   };
   mock?: {
+    /** Local response delay in ms, [minMs, maxMs], or an object range. Defaults to [30, 100]. Use 0 to disable. */
     delay?: number | [number, number] | {
       minMs?: number;
       maxMs?: number;
       min?: number;
       max?: number;
     } | null;
+    /** Random local error rate or detailed error settings. Defaults to no random errors. */
     errors?: number | {
       rate?: number;
       probability?: number;
@@ -65,11 +98,14 @@ export type JsonDbOptions = {
   };
   generate?: {
     hono?: {
+      /** Output folder for generated starter code. */
       outDir?: string;
+      /** API modules to generate. */
       api?: Array<'rest' | 'graphql'> | 'rest' | 'graphql' | 'rest,graphql' | 'none';
       db?: 'sqlite';
       app?: 'standalone' | 'module';
       runtime?: 'node-sqlite';
+      /** Include fixture seed support in generated starter code. */
       seed?: false | 'fixtures';
     };
   };

src/index.d.ts

@@ -13,6 +13,17 @@ test('mock delay supports range arrays', () => {
   assert.equal(pickDelayMs(delay, () => 1), 300);
 });
 
+test('mock delay supports disabled and fixed values', () => {
+  assert.deepEqual(normalizeMockDelay(0), {
+    minMs: 0,
+    maxMs: 0,
+  });
+  assert.deepEqual(normalizeMockDelay(50), {
+    minMs: 50,
+    maxMs: 50,
+  });
+});
+
 test('mock errors can force chaos responses', async () => {
   const result = await runMockBehavior({
     mock: {

src/mock.test.js

@@ -7,6 +7,7 @@ export async function makeProject() {
   await mkdir(path.join(cwd, 'db'), { recursive: true });
   await mkdir(path.join(cwd, 'node_modules'), { recursive: true });
   await symlink(path.resolve('.'), path.join(cwd, 'node_modules', 'json-fixture-db'), 'dir');
+  await symlink(path.resolve('.'), path.join(cwd, 'node_modules', 'jsondb'), 'dir');
   return cwd;
 }
 

test/helpers.js

@@ -28,6 +28,13 @@ test('data-first fixtures generate schema, types, and runtime state', async () =
   assert.deepEqual(JSON.parse(await readFile(path.join(cwd, '.jsondb/state/users.json'), 'utf8'))[0].id, 'u_1');
 });
 
+test('default config adds a small local mock delay range', async () => {
+  const cwd = await makeProject();
+  const config = await loadConfig({ cwd });
+
+  assert.deepEqual(config.mock.delay, [30, 100]);
+});
+
 test('dbDir config changes the fixture source folder', async () => {
   const cwd = await makeProject();
   await writeConfig(cwd, `export default {
@@ -57,6 +64,38 @@ test('dbDir config changes the fixture source folder', async () => {
   assert.equal(metadata.resources.users.path, 'jsondb/users.json');
 });
 
+test('config files can use the typed defineConfig helper', async () => {
+  const cwd = await makeProject();
+  await writeConfig(cwd, `import { defineConfig } from 'jsondb/config';
+
+export default defineConfig({
+  mode: 'mirror',
+  mock: {
+    delay: [75, 250],
+  },
+});
+`);
+
+  const config = await loadConfig({ cwd });
+
+  assert.equal(config.mode, 'mirror');
+  assert.deepEqual(config.mock.delay, [75, 250]);
+});
+
+test('consumer projects can import package APIs through the jsondb alias', async () => {
+  const cwd = await makeProject();
+  await writeFile(path.join(cwd, 'check-alias.mjs'), `import { openJsonFixtureDb } from 'jsondb';
+import { createJsonDbClient } from 'jsondb/client';
+import { defineConfig } from 'jsondb/config';
+
+if (typeof openJsonFixtureDb !== 'function') throw new Error('missing package API');
+if (typeof createJsonDbClient !== 'function') throw new Error('missing client API');
+if (typeof defineConfig !== 'function') throw new Error('missing config API');
+`);
+
+  await execFileAsync(process.execPath, ['check-alias.mjs'], { cwd });
+});
+
 test('schema-only fixtures generate types and initialize empty state', async () => {
   const cwd = await makeProject();
   await writeFixture(cwd, 'auditEvents.schema.jsonc', `{
@@ -220,7 +259,7 @@ test('package API duplicate ids produce actionable errors', async () => {
 
 test('.schema.mjs files can use schema helpers', async () => {
   const cwd = await makeProject();
-  await writeFixture(cwd, 'users.schema.mjs', `import { collection, field } from 'json-fixture-db/schema';
+  await writeFixture(cwd, 'users.schema.mjs', `import { collection, field } from 'jsondb/schema';
 
 export default collection({
   idField: 'id',