dynalitics 0.0.0-stage → 0.1.0

package/dist/config/schema.js

@@ -0,0 +1,248 @@
+import { ADAPTER_API_VERSION } from '../adapter-version.js';
+import { DynaliticsConfigError } from '../errors.js';
+import { assertTableForDialect, parseTableRef } from '../model/identifiers.js';
+import { anyObject, bool, custom, fn, int, obj, oneOf, rec, req, runRule, str, } from './validate.js';
+const ROLES = [
+    'timestamp',
+    'consent',
+    'pageVisited',
+    'ip',
+    'userId',
+    'username',
+    'email',
+    'custom',
+    'isFirstVisit',
+    'id',
+];
+const MIN_SALT = 16;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const credentialRule = (v, path, issues) => {
+    if (!isObj(v))
+        return void issues.push(`${path}: expected an object`);
+    const hasCs = Object.hasOwn(v, 'connectionString');
+    const hasPool = Object.hasOwn(v, 'pool');
+    if (hasCs && hasPool)
+        return void issues.push(`${path}: provide exactly one of connectionString or pool`);
+    if (!hasCs && !hasPool)
+        return void issues.push(`${path}: provide connectionString or pool`);
+    obj({ connectionString: str({ min: 1 }), pool: anyObject })(v, path, issues);
+};
+const connectionRule = (v, path, issues) => {
+    if (!isObj(v))
+        return void issues.push(`${path}: expected an object`);
+    const single = Object.hasOwn(v, 'connectionString') || Object.hasOwn(v, 'pool');
+    const split = Object.hasOwn(v, 'writer') || Object.hasOwn(v, 'reader');
+    if (single && split) {
+        return void issues.push(`${path}: use either a single credential (connectionString or pool) or { writer, reader }, not both`);
+    }
+    if (single)
+        return credentialRule(v, path, issues);
+    if (!split)
+        return void issues.push(`${path}: provide connectionString, pool, or { writer, reader }`);
+    obj({ writer: credentialRule, reader: credentialRule })(v, path, issues);
+};
+const DIALECTS = ['postgres', 'mysql', 'mssql'];
+const ADAPTER_HINT = 'expected an adapter from dynalitics-postgres, dynalitics-mysql or dynalitics-mssql';
+/** Spec 5.2 (v0.5): structural check, so an adapter built against another copy of dynalitics still passes. */
+const adapterRule = (v, path, issues) => {
+    if (!isObj(v))
+        return void issues.push(`${path}: ${ADAPTER_HINT}`);
+    const { apiVersion, dialect, createDriver, packageName } = v;
+    if (typeof createDriver !== 'function' || !DIALECTS.includes(dialect))
+        return void issues.push(`${path}: ${ADAPTER_HINT}`);
+    if (apiVersion !== ADAPTER_API_VERSION) {
+        const name = typeof packageName === 'string' ? packageName : 'the adapter';
+        issues.push(`${path}: ${name} implements adapter API ${String(apiVersion)}, this dynalitics needs ${ADAPTER_API_VERSION}`);
+    }
+};
+const dialectOf = (c) => {
+    const a = c['adapter'];
+    return isObj(a) && DIALECTS.includes(a['dialect'])
+        ? a['dialect']
+        : undefined;
+};
+const tableRule = (v, path, issues) => {
+    if (typeof v === 'string')
+        return str({ min: 1 })(v, path, issues);
+    if (isObj(v))
+        return obj({ database: str(), schema: str(), name: req(str({ min: 1 })) })(v, path, issues);
+    issues.push(`${path}: expected a string or { schema?, name }`);
+};
+const columnsRule = obj(Object.fromEntries(ROLES.map((role) => [
+    role,
+    custom((v, path, issues) => {
+        if (v !== false && typeof v !== 'string')
+            issues.push(`${path}: expected a column name or false`);
+    }),
+])));
+const customFieldRule = obj({
+    type: req(oneOf(['string', 'integer', 'number', 'boolean'])),
+    maxLength: int({ min: 1, max: 1024 }),
+    personal: bool,
+    column: custom((v, path, issues) => {
+        if (v !== true && typeof v !== 'string')
+            issues.push(`${path}: expected true or a column name`);
+    }),
+    breakdown: bool,
+    keepWhenDenied: bool,
+});
+const notYet = (what) => (_v, path, issues) => void issues.push(`${path}: ${what} is not supported yet (planned for phase 2)`);
+const configRule = obj({
+    adapter: req(adapterRule),
+    connection: req(connectionRule),
+    acknowledgeSingleCredential: bool,
+    poolSize: int({ min: 1, max: 20 }),
+    connectTimeoutMs: int({ min: 100, max: 120_000 }),
+    table: req(tableRule),
+    tableMode: oneOf(['recommended', 'existing']),
+    columns: columnsRule,
+    customFields: rec(customFieldRule),
+    extraColumns: notYet('extraColumns'),
+    page: obj({ keepQuery: bool, maxLength: int({ min: 1, max: 700 }), normalize: fn }),
+    ip: obj({
+        mode: oneOf(['raw', 'hash', 'truncate']),
+        salt: str(),
+        ipv4Prefix: int({ min: 8, max: 32 }),
+        ipv6Prefix: int({ min: 16, max: 128 }),
+    }),
+    consent: obj({ default: fn }),
+    firstVisit: obj({ enabled: bool, cacheSize: int({ min: 1, max: 5_000_000 }) }),
+    queue: obj({
+        maxSize: int({ min: 1, max: 1_000_000 }),
+        batchSize: int({ min: 1, max: 1000 }),
+        flushIntervalMs: int({ min: 10, max: 600_000 }),
+        backpressure: oneOf(['drop', 'block']),
+        maxBlockMs: int({ min: 1, max: 600_000 }),
+        retry: obj({
+            attempts: int({ min: 1, max: 10 }),
+            baseDelayMs: int({ min: 1, max: 60_000 }),
+            maxDelayMs: int({ min: 1, max: 600_000 }),
+        }),
+    }),
+    limits: obj({
+        customMaxKeys: int({ min: 1, max: 100 }),
+        customMaxBytes: int({ min: 16, max: 65_536 }),
+        oversize: oneOf(['truncate', 'reject']),
+    }),
+    validateOnStart: oneOf(['strict', 'skip']),
+    onError: fn,
+    logger: custom((v, path, issues) => {
+        if (!isObj(v))
+            return void issues.push(`${path}: expected an object with info, warn and error functions`);
+        obj({ info: req(fn), warn: req(fn), error: req(fn) })(v, path, issues);
+    }),
+});
+/** Rule for the JSON file accepted by `dynalitics sql --config`: table-shape settings only, no secrets, no functions. */
+export const schemaFileRule = obj({
+    tableMode: oneOf(['recommended', 'existing']),
+    columns: columnsRule,
+    customFields: rec(customFieldRule),
+    page: obj({ maxLength: int({ min: 1, max: 700 }) }),
+    firstVisit: obj({ enabled: bool }),
+});
+function crossChecks(c, issues) {
+    if (c['tableMode'] === 'existing' && c['validateOnStart'] === 'skip') {
+        issues.push('config.validateOnStart: "skip" is only allowed with tableMode "recommended"; an existing table is always checked at startup');
+    }
+    const ip = c['ip'];
+    if (isObj(ip) && ip['mode'] === 'hash') {
+        const salt = ip['salt'];
+        if (salt === undefined)
+            issues.push('config.ip.salt is required when ip.mode is "hash"');
+        else if (typeof salt === 'string' && salt.length < MIN_SALT) {
+            issues.push(`config.ip.salt must be at least ${MIN_SALT} characters`);
+        }
+    }
+    const table = c['table'];
+    const dialect = dialectOf(c);
+    if ((typeof table === 'string' || isObj(table)) && dialect !== undefined) {
+        try {
+            const ref = parseTableRef(table);
+            assertTableForDialect(ref, dialect);
+        }
+        catch (e) {
+            if (e instanceof DynaliticsConfigError)
+                issues.push(...e.issues.map((m) => `config.table: ${m}`));
+            else
+                throw e;
+        }
+    }
+}
+/** Shape and cross-field validation. Throws one DynaliticsConfigError listing every issue. */
+export function validateConfig(input) {
+    if (!isObj(input))
+        throw new DynaliticsConfigError(['config: expected an object']);
+    const issues = runRule(configRule, input, 'config');
+    crossChecks(input, issues);
+    if (issues.length > 0)
+        throw new DynaliticsConfigError(issues);
+    return input;
+}
+function resolveCredentials(connection) {
+    if ('connectionString' in connection || 'pool' in connection) {
+        const cred = connection;
+        return { single: true, writer: cred, reader: cred };
+    }
+    const split = connection;
+    return {
+        single: false,
+        ...(split.writer === undefined ? {} : { writer: split.writer }),
+        ...(split.reader === undefined ? {} : { reader: split.reader }),
+    };
+}
+/** Applies defaults (spec 4.3). Pure: returns a new object, never mutates the config. */
+export function resolveConfig(c) {
+    return {
+        adapter: c.adapter,
+        dialect: c.adapter.dialect,
+        credentials: resolveCredentials(c.connection),
+        acknowledgeSingleCredential: c.acknowledgeSingleCredential === true,
+        poolSize: { writer: c.poolSize ?? 4, reader: c.poolSize ?? 2 },
+        connectTimeoutMs: c.connectTimeoutMs ?? 10_000,
+        schema: {
+            table: c.table,
+            ...(c.tableMode === undefined ? {} : { tableMode: c.tableMode }),
+            ...(c.columns === undefined ? {} : { columns: c.columns }),
+            ...(c.customFields === undefined ? {} : { customFields: c.customFields }),
+            page: { maxLength: c.page?.maxLength ?? 512 },
+            firstVisit: { enabled: c.firstVisit?.enabled === true },
+        },
+        page: {
+            keepQuery: c.page?.keepQuery === true,
+            maxLength: c.page?.maxLength ?? 512,
+            normalize: c.page?.normalize,
+        },
+        ip: {
+            mode: c.ip?.mode ?? 'truncate',
+            salt: c.ip?.salt,
+            ipv4Prefix: c.ip?.ipv4Prefix ?? 24,
+            ipv6Prefix: c.ip?.ipv6Prefix ?? 48,
+        },
+        consentDefault: c.consent?.default,
+        firstVisit: {
+            enabled: c.firstVisit?.enabled === true,
+            cacheSize: c.firstVisit?.cacheSize ?? 50_000,
+        },
+        queue: {
+            maxSize: c.queue?.maxSize ?? 10_000,
+            batchSize: c.queue?.batchSize ?? 200,
+            flushIntervalMs: c.queue?.flushIntervalMs ?? 1000,
+            backpressure: c.queue?.backpressure ?? 'drop',
+            maxBlockMs: c.queue?.maxBlockMs ?? 2000,
+            retry: {
+                attempts: c.queue?.retry?.attempts ?? 3,
+                baseDelayMs: c.queue?.retry?.baseDelayMs ?? 200,
+                maxDelayMs: c.queue?.retry?.maxDelayMs ?? 5000,
+            },
+        },
+        limits: {
+            customMaxKeys: c.limits?.customMaxKeys ?? 20,
+            customMaxBytes: c.limits?.customMaxBytes ?? 4096,
+            oversize: c.limits?.oversize ?? 'truncate',
+        },
+        validateOnStart: c.validateOnStart ?? 'strict',
+        onError: c.onError,
+        logger: c.logger,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/config/validate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A tiny declarative validator (no dependencies). Each rule appends human-readable issues with a dotted path;
+ * nothing throws, so the caller can report every problem at once. Values are never echoed back, only their kind,
+ * so secrets cannot leak through validation messages.
+ */
+export type Issues = string[];
+export type Rule = (value: unknown, path: string, issues: Issues) => void;
+export declare const str: (o?: {
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+    hint?: string;
+}) => Rule;
+export declare const int: (o: {
+    min: number;
+    max: number;
+}) => Rule;
+export declare const bool: Rule;
+export declare const oneOf: (allowed: readonly string[]) => Rule;
+export declare const fn: Rule;
+export declare const anyObject: Rule;
+/** Marks a key as required inside obj(). */
+export declare const req: (rule: Rule) => Rule & {
+    required: true;
+};
+export declare const obj: (shape: Readonly<Record<string, Rule>>) => Rule;
+export declare const rec: (rule: Rule) => Rule;
+export declare const custom: (check: (value: unknown, path: string, issues: Issues) => void) => Rule;
+export declare function runRule(rule: Rule, value: unknown, path: string): Issues;
+//# sourceMappingURL=validate.d.ts.map

package/dist/config/validate.js

@@ -0,0 +1,68 @@
+const kindOf = (v) => v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v;
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const str = (o = {}) => (v, path, issues) => {
+    if (typeof v !== 'string')
+        return void issues.push(`${path}: expected a string, got ${kindOf(v)}`);
+    if (o.min !== undefined && v.length < o.min)
+        issues.push(`${path}: expected at least ${o.min} characters`);
+    if (o.max !== undefined && v.length > o.max)
+        issues.push(`${path}: expected at most ${o.max} characters`);
+    if (o.pattern !== undefined && !o.pattern.test(v))
+        issues.push(`${path}: ${o.hint ?? 'has an invalid format'}`);
+};
+export const int = (o) => (v, path, issues) => {
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < o.min || v > o.max) {
+        issues.push(`${path}: expected integer ${o.min}..${o.max}, got ${typeof v === 'number' ? String(v) : kindOf(v)}`);
+    }
+};
+export const bool = (v, path, issues) => {
+    if (typeof v !== 'boolean')
+        issues.push(`${path}: expected a boolean, got ${kindOf(v)}`);
+};
+export const oneOf = (allowed) => (v, path, issues) => {
+    if (typeof v !== 'string' || !allowed.includes(v)) {
+        issues.push(`${path}: expected one of ${allowed.map((a) => JSON.stringify(a)).join(', ')}`);
+    }
+};
+export const fn = (v, path, issues) => {
+    if (typeof v !== 'function')
+        issues.push(`${path}: expected a function, got ${kindOf(v)}`);
+};
+export const anyObject = (v, path, issues) => {
+    if (typeof v !== 'object' || v === null)
+        issues.push(`${path}: expected an object, got ${kindOf(v)}`);
+};
+/** Marks a key as required inside obj(). */
+export const req = (rule) => Object.assign((v, path, issues) => rule(v, path, issues), {
+    required: true,
+});
+export const obj = (shape) => (v, path, issues) => {
+    if (!isPlainObject(v))
+        return void issues.push(`${path}: expected an object, got ${kindOf(v)}`);
+    for (const key of Object.keys(v)) {
+        if (!Object.hasOwn(shape, key))
+            issues.push(`${path}.${key}: unknown key`);
+    }
+    for (const [key, rule] of Object.entries(shape)) {
+        const present = Object.hasOwn(v, key) && v[key] !== undefined;
+        if (!present) {
+            if (rule.required === true)
+                issues.push(`${path}.${key}: required`);
+            continue;
+        }
+        rule(v[key], `${path}.${key}`, issues);
+    }
+};
+export const rec = (rule) => (v, path, issues) => {
+    if (!isPlainObject(v))
+        return void issues.push(`${path}: expected an object, got ${kindOf(v)}`);
+    for (const [key, value] of Object.entries(v))
+        rule(value, `${path}.${key}`, issues);
+};
+export const custom = (check) => (v, path, issues) => check(v, path, issues);
+export function runRule(rule, value, path) {
+    const issues = [];
+    rule(value, path, issues);
+    return issues;
+}
+//# sourceMappingURL=validate.js.map

package/dist/create.d.ts

@@ -0,0 +1,16 @@
+import { type Driver, type DriverAdapter, type DriverOptions } from './driver/types.js';
+import type { Dynalitics, DynaliticsConfig } from './types.js';
+export interface CreateDeps {
+    readonly createDriver: (adapter: DriverAdapter, options: DriverOptions) => Promise<Driver>;
+    readonly now: () => Date;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly random: () => number;
+}
+/** Same as createDynalitics but with injectable I/O, for tests. */
+export declare function createDynaliticsWith(config: DynaliticsConfig, deps: CreateDeps): Promise<Dynalitics>;
+/**
+ * Connects, validates the table (never changes it) and returns a tracker.
+ * Throws DynaliticsConfigError, DynaliticsConnectionError or DynaliticsSchemaError (never with connection details).
+ */
+export declare function createDynalitics(config: DynaliticsConfig): Promise<Dynalitics>;
+//# sourceMappingURL=create.d.ts.map

package/dist/create.js

@@ -0,0 +1,308 @@
+import { randomBytes } from 'node:crypto';
+import { resolveConfig, validateConfig } from './config/schema.js';
+import { getDialect } from './dialect/index.js';
+import { isDriverError, } from './driver/types.js';
+import { DynaliticsConnectionError, DynaliticsSchemaError } from './errors.js';
+import { registerInternals } from './internals.js';
+import { consoleLogger, safeLogger } from './logger.js';
+import { buildColumnModel } from './model/column-model.js';
+import { adoptPhysical } from './model/physical.js';
+import { createPipeline } from './queue/pipeline.js';
+import { createRedactor, sanitizeError, secretsFromConnectionString, } from './redact.js';
+import { createReporter } from './report.js';
+import { compareTable } from './startup/compare.js';
+import { buildFixSql, buildSchemaReport } from './startup/fix-sql.js';
+import { inspectPrivileges } from './startup/privileges.js';
+import { probeSessionTimeDiff } from './startup/session-timezone.js';
+import { unmappedNotice } from './startup/unmapped-notice.js';
+import { buildRow } from './track/build-row.js';
+import { createFirstVisit } from './track/first-visit.js';
+const realDeps = {
+    createDriver: (adapter, options) => adapter.createDriver(options),
+    now: () => new Date(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    random: Math.random,
+};
+const STARTUP_QUERY_TIMEOUT_MS = 10_000;
+const SINGLE_CREDENTIAL_WARNING = "dynalitics is using ONE database credential for both writing and reading. Anyone who can use the web process's credential can therefore read the personal data (ip, email, username, userId) it writes. Use separate writer and reader credentials: `npx dynalitics sql --grants-only --dialect <dialect> --table <table>` prints the GRANT statements.";
+const secretsOf = (c) => c !== undefined && 'connectionString' in c ? secretsFromConnectionString(c.connectionString) : [];
+function asConnectionError(err, what, redact) {
+    if (err instanceof DynaliticsConnectionError)
+        return err;
+    const cause = isDriverError(err)
+        ? (err.safeCause ?? sanitizeError(err, redact))
+        : sanitizeError(err, redact);
+    return new DynaliticsConnectionError(`${what}: ${cause.message}`, cause);
+}
+/** MySQL: a TIMESTAMP role column makes the session time zone matter (spec 3.9). Nothing is asked otherwise. */
+async function sessionTimeDiffFor(model, columns, dialect, drivers, redact) {
+    const ts = model.columns.find((c) => c.role === 'timestamp');
+    const real = columns.find((c) => c.name.toLowerCase() === ts?.name.toLowerCase());
+    if (dialect.name !== 'mysql' || real?.dataType !== 'timestamp')
+        return undefined;
+    try {
+        return await probeSessionTimeDiff(drivers, STARTUP_QUERY_TIMEOUT_MS);
+    }
+    catch (err) {
+        throw asConnectionError(err, 'Could not check the session time zone', redact);
+    }
+}
+async function checkStructure(inspector, used, hasReader, model, dialect, logger, redact) {
+    let rows;
+    try {
+        rows = await inspector.query(dialect.introspectSql(model.table), {
+            timeoutMs: STARTUP_QUERY_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        throw asConnectionError(err, 'Could not read the table structure', redact);
+    }
+    const columns = rows.map((r) => dialect.mapColumnRow(r));
+    const sessionTimeDiff = await sessionTimeDiffFor(model, columns, dialect, used, redact);
+    const result = compareTable({
+        model,
+        dialect,
+        columns,
+        ...(sessionTimeDiff === undefined ? {} : { sessionTimeDiff }),
+    });
+    let problems = result.problems;
+    if (!hasReader && columns.length === 0) {
+        const table = dialect.qualifiedTable(model.table);
+        problems = [
+            {
+                code: 'identity_not_discoverable',
+                message: model.mode === 'existing'
+                    ? `The writer credential cannot see the columns of ${table} (or the table does not exist), so the structure cannot be checked. Add a reader credential that can see the table, and check the table name in the config.`
+                    : `The writer credential cannot see the columns of ${table} (or the table does not exist), so the structure cannot be checked. Add a reader credential, or set validateOnStart: 'skip'. To get the recommended table, run: npx dynalitics sql --dialect ${dialect.name} --table ${model.table.name}`,
+            },
+        ];
+    }
+    if (problems.length > 0) {
+        const input = { model, dialect, problems, warnings: result.warnings };
+        throw new DynaliticsSchemaError(buildSchemaReport(input), problems, result.warnings, buildFixSql(input));
+    }
+    for (const w of result.warnings)
+        logger.warn(w.message);
+    return { schema: columns[0]?.schema, columns };
+}
+/** Same as createDynalitics but with injectable I/O, for tests. */
+export async function createDynaliticsWith(config, deps) {
+    const cfg = resolveConfig(validateConfig(config));
+    let model = buildColumnModel(cfg.schema);
+    const dialect = getDialect(cfg.dialect);
+    const { writer: writerCred, reader: readerCred, single } = cfg.credentials;
+    const redact = createRedactor([
+        ...secretsOf(writerCred),
+        ...secretsOf(readerCred),
+        ...(cfg.ip.salt === undefined ? [] : [cfg.ip.salt]),
+    ]);
+    const logger = safeLogger(cfg.logger ?? consoleLogger, redact);
+    const reporter = createReporter(cfg.onError, redact, deps.now);
+    if (single && !cfg.acknowledgeSingleCredential)
+        logger.warn(SINGLE_CREDENTIAL_WARNING);
+    const opened = [];
+    const closeAll = async () => {
+        await Promise.allSettled([...new Set(opened)].map((d) => d.close()));
+    };
+    const open = async (cred, max) => {
+        try {
+            const d = await deps.createDriver(cfg.adapter, {
+                credential: cred,
+                max,
+                connectTimeoutMs: cfg.connectTimeoutMs,
+                redact,
+            });
+            opened.push(d);
+            return d;
+        }
+        catch (err) {
+            throw asConnectionError(err, 'Could not set up the database driver', redact);
+        }
+    };
+    let writerDriver;
+    let readerDriver;
+    let adopted = [];
+    try {
+        if (writerCred !== undefined)
+            writerDriver = await open(writerCred, cfg.poolSize.writer);
+        if (single)
+            readerDriver = writerDriver;
+        else if (readerCred !== undefined)
+            readerDriver = await open(readerCred, cfg.poolSize.reader);
+        if (cfg.validateOnStart === 'skip') {
+            logger.warn('validateOnStart is "skip": the table structure and privileges were NOT checked.');
+        }
+        else {
+            for (const d of new Set([writerDriver, readerDriver])) {
+                if (d === undefined)
+                    continue;
+                try {
+                    await d.query({ sql: 'SELECT 1', params: [] }, { timeoutMs: cfg.connectTimeoutMs });
+                }
+                catch (err) {
+                    throw asConnectionError(err, 'Could not connect to the database', redact);
+                }
+            }
+            const inspector = readerDriver ?? writerDriver;
+            if (inspector !== undefined) {
+                const used = [...new Set([writerDriver, readerDriver])].filter((d) => d !== undefined);
+                const found = await checkStructure(inspector, used, readerDriver !== undefined, model, dialect, logger, redact);
+                const real = adoptPhysical(model, found.columns, dialect.name);
+                model = real.model;
+                adopted = real.adopted;
+                if (found.schema !== undefined && model.table.schema === undefined) {
+                    // Introspection and INSERT/SELECT must look at the same table, not at whatever search_path resolves later.
+                    model = { ...model, table: { ...model.table, schema: found.schema } };
+                }
+            }
+            const checks = single
+                ? [[writerDriver, 'single']]
+                : [
+                    [writerDriver, 'writer'],
+                    [readerDriver, 'reader'],
+                ];
+            for (const [driver, kind] of checks) {
+                if (driver === undefined)
+                    continue;
+                const r = await inspectPrivileges({
+                    driver,
+                    dialect,
+                    table: model.table,
+                    kind,
+                    firstVisitEnabled: model.firstVisitEnabled,
+                });
+                if (r.warning !== undefined)
+                    logger.warn(r.warning);
+            }
+        }
+    }
+    catch (err) {
+        await closeAll();
+        throw err;
+    }
+    logger.info(`using table ${dialect.qualifiedTable(model.table)} (tableMode "${model.mode}")`);
+    for (const a of adopted) {
+        logger.info(`column "${a.column}" holds at most ${a.real} characters, less than the configured ${a.configured}; longer values are ${cfg.limits.oversize === 'reject' ? 'rejected' : 'cut to fit'}.`);
+    }
+    const notice = unmappedNotice(model);
+    if (notice !== undefined)
+        logger.info(notice);
+    const firstVisit = model.firstVisitEnabled && writerDriver !== undefined
+        ? createFirstVisit({
+            cacheSize: cfg.firstVisit.cacheSize,
+            processKey: randomBytes(32),
+            maxParams: dialect.limits.maxParams,
+            lookup: async (kind, values) => {
+                const rows = await writerDriver.query(dialect.firstVisitLookup(model, kind, values), {
+                    timeoutMs: STARTUP_QUERY_TIMEOUT_MS,
+                });
+                return new Set(rows.map((r) => String(r['v'])));
+            },
+        })
+        : undefined;
+    const pipeline = writerDriver === undefined
+        ? undefined
+        : createPipeline({
+            driver: writerDriver,
+            dialect,
+            model,
+            queue: cfg.queue,
+            firstVisit,
+            report: (info) => reporter.report(info),
+            sleep: (ms) => deps.sleep(ms),
+            random: () => deps.random(),
+            now: () => deps.now().getTime(),
+            requestTimeoutMs: STARTUP_QUERY_TIMEOUT_MS,
+        });
+    let rejected = 0;
+    const pageColumn = model.columns.find((c) => c.role === 'pageVisited')?.type;
+    const rowConfig = {
+        // The real column may be shorter than page.maxLength (existing tables): never build a value that cannot be stored.
+        page: {
+            ...cfg.page,
+            maxLength: pageColumn?.kind === 'string' ? pageColumn.maxLength : cfg.page.maxLength,
+        },
+        ip: cfg.ip,
+        limits: cfg.limits,
+        consentDefault: cfg.consentDefault,
+    };
+    let closing;
+    const dyn = {
+        model,
+        table: model.table,
+        capabilities: { canWrite: pipeline !== undefined, canRead: readerDriver !== undefined },
+        async track(visit) {
+            try {
+                if (pipeline === undefined)
+                    return { status: 'rejected', issues: ['no writer credential configured'] };
+                const built = buildRow({ model, dialect, cfg: rowConfig, visit, now: deps.now() });
+                built.notes.forEach((n) => reporter.note(n));
+                if (!built.ok) {
+                    rejected++;
+                    reporter.note({
+                        code: 'invalid_visit',
+                        message: `visit rejected: ${built.issues.join('; ')}`,
+                    });
+                    return { status: 'rejected', issues: built.issues };
+                }
+                return await pipeline.enqueue({ values: built.values, identity: built.identity });
+            }
+            catch (err) {
+                rejected++;
+                reporter.report({
+                    code: 'internal',
+                    message: 'unexpected error while tracking a visit',
+                    cause: sanitizeError(err, redact),
+                });
+                return { status: 'rejected', issues: ['internal error'] };
+            }
+        },
+        async flush(opts) {
+            return pipeline === undefined
+                ? { written: 0, failed: 0, timedOut: false }
+                : pipeline.flush(opts);
+        },
+        close(opts) {
+            closing ??= (async () => {
+                const res = pipeline === undefined
+                    ? { written: 0, failed: 0, timedOut: false }
+                    : await pipeline.close(opts);
+                await closeAll();
+                return res;
+            })();
+            return closing;
+        },
+        stats() {
+            const s = pipeline?.stats();
+            return {
+                queued: s?.queued ?? 0,
+                written: s?.written ?? 0,
+                droppedFull: s?.droppedFull ?? 0,
+                rejected,
+                failed: s?.failed ?? 0,
+                queueLength: s?.queueLength ?? 0,
+                lruSize: firstVisit?.size() ?? 0,
+                lastErrorAt: reporter.lastErrorAt(),
+            };
+        },
+    };
+    registerInternals(dyn, {
+        reader: readerDriver,
+        dialect,
+        model,
+        ipMode: cfg.ip.mode,
+        redact,
+        report: (info) => reporter.report(info),
+        logger,
+        now: deps.now,
+    });
+    return dyn;
+}
+/**
+ * Connects, validates the table (never changes it) and returns a tracker.
+ * Throws DynaliticsConfigError, DynaliticsConnectionError or DynaliticsSchemaError (never with connection details).
+ */
+export function createDynalitics(config) {
+    return createDynaliticsWith(config, realDeps);
+}
+//# sourceMappingURL=create.js.map