dynalitics 0.0.0-stage → 0.1.0

package/dist/model/identifiers.js

@@ -0,0 +1,62 @@
+import { DynaliticsConfigError } from '../errors.js';
+/** The ONLY way identifiers (table, schema, column names) enter SQL. Quoting is added on top as defence in depth. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+const CUSTOM_KEY = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+export function isIdentifier(name) {
+    return typeof name === 'string' && IDENTIFIER.test(name);
+}
+export function isCustomKey(name) {
+    return typeof name === 'string' && CUSTOM_KEY.test(name) && !FORBIDDEN_KEYS.has(name);
+}
+export function identifierMessage(name, what) {
+    return `Identifier ${JSON.stringify(name)} (${what}) is not supported. Allowed: letters, digits and underscore, starting with a letter or underscore, at most 63 characters. Create a view or rename the object.`;
+}
+export function assertIdentifier(name, what) {
+    if (!isIdentifier(name))
+        throw new DynaliticsConfigError([identifierMessage(name, what)]);
+    return name;
+}
+export function assertCustomKey(key) {
+    if (!isCustomKey(key)) {
+        throw new DynaliticsConfigError([
+            `${JSON.stringify(key)} is not a valid custom field key. Allowed: ^[A-Za-z_][A-Za-z0-9_]{0,63}$ (not __proto__, constructor or prototype).`,
+        ]);
+    }
+    return key;
+}
+/** Parses 'name', 'schema.name', 'db.schema.name' or an object into a validated TableRef. */
+export function parseTableRef(input) {
+    const parts = typeof input === 'string' ? splitTableString(input) : input;
+    const checked = (value, what) => assertIdentifier(value, what);
+    return {
+        ...(parts.database === undefined
+            ? {}
+            : { database: checked(parts.database, 'table database') }),
+        ...(parts.schema === undefined ? {} : { schema: checked(parts.schema, 'table schema') }),
+        name: checked(parts.name, 'table name'),
+    };
+}
+function splitTableString(input) {
+    const segments = input.split('.');
+    if (segments.length > 3) {
+        throw new DynaliticsConfigError(['Table name has at most 3 parts: database.schema.name.']);
+    }
+    const [a = '', b, c] = segments;
+    if (segments.length === 1)
+        return { name: a };
+    if (segments.length === 2)
+        return { schema: a, name: b ?? '' };
+    return { database: a, schema: b ?? '', name: c ?? '' };
+}
+/** Dialect-specific restrictions on table references (spec 3.7). */
+export function assertTableForDialect(ref, dialect) {
+    if (ref.database !== undefined && dialect !== 'mssql') {
+        throw new DynaliticsConfigError([
+            dialect === 'postgres'
+                ? 'PostgreSQL tables are addressed as name or schema.name; cross-database names do not exist.'
+                : 'MySQL tables are addressed as name or schema.name, where "schema" means the database.',
+        ]);
+    }
+}
+//# sourceMappingURL=identifiers.js.map

package/dist/model/physical.d.ts

@@ -0,0 +1,19 @@
+import type { ColumnInfo } from '../dialect/types.js';
+import type { ColumnDef, ColumnModel, Dialect } from './types.js';
+export interface LengthAdoption {
+    readonly column: string;
+    readonly configured: number;
+    readonly real: number;
+}
+/** True if the real column is an integer type, so a boolean has to be bound as 1/0 (and read as a number). */
+export declare const isIntegerColumn: (c: ColumnDef | undefined) => boolean;
+/**
+ * Returns a copy of the model that knows the real database types (from the catalog). In `existing` mode string
+ * columns also adopt the real length when it is shorter than configured (spec 7.2); unlimited types keep the configured
+ * maximum. Recommended tables keep their lengths: a shorter real column is the `too_short` problem there.
+ */
+export declare function adoptPhysical(model: ColumnModel, catalog: readonly ColumnInfo[], dialect: Dialect): {
+    readonly model: ColumnModel;
+    readonly adopted: readonly LengthAdoption[];
+};
+//# sourceMappingURL=physical.d.ts.map

package/dist/model/physical.js

@@ -0,0 +1,70 @@
+const INTEGER_TYPES = new Set([
+    'int2',
+    'int4',
+    'int8',
+    'smallint',
+    'integer',
+    'bigint',
+    'tinyint',
+    'mediumint',
+    'int',
+]);
+/** True if the real column is an integer type, so a boolean has to be bound as 1/0 (and read as a number). */
+export const isIntegerColumn = (c) => c?.physicalType !== undefined && INTEGER_TYPES.has(c.physicalType);
+/**
+ * Returns a copy of the model that knows the real database types (from the catalog). In `existing` mode string
+ * columns also adopt the real length when it is shorter than configured (spec 7.2); unlimited types keep the configured
+ * maximum. Recommended tables keep their lengths: a shorter real column is the `too_short` problem there.
+ */
+export function adoptPhysical(model, catalog, dialect) {
+    const key = (n) => (dialect === 'postgres' ? n : n.toLowerCase());
+    const byName = new Map(catalog.map((c) => [key(c.name), c]));
+    const adopted = [];
+    const refine = (c) => {
+        const info = byName.get(key(c.name));
+        if (info === undefined)
+            return c;
+        const withType = { ...c, physicalType: info.dataType };
+        if (model.mode === 'existing' &&
+            c.type.kind === 'string' &&
+            info.maxLength !== null &&
+            info.maxLength > 0 &&
+            info.maxLength < c.type.maxLength) {
+            adopted.push({ column: c.name, configured: c.type.maxLength, real: info.maxLength });
+            return { ...withType, type: { kind: 'string', maxLength: info.maxLength } };
+        }
+        return withType;
+    };
+    const columns = model.columns.map(refine);
+    const byColumnName = new Map(columns.map((c) => [c.name, c]));
+    const byRole = (role) => columns.find((c) => c.role === role);
+    const customFields = new Map();
+    for (const [name, field] of model.customFields) {
+        const column = field.column === undefined ? undefined : byColumnName.get(field.column.name);
+        customFields.set(name, {
+            ...field,
+            ...(column === undefined
+                ? {}
+                : {
+                    column,
+                    maxLength: column.type.kind === 'string' ? column.type.maxLength : field.maxLength,
+                }),
+        });
+    }
+    const userId = byRole('userId');
+    const ip = byRole('ip');
+    return {
+        model: {
+            ...model,
+            columns,
+            insertColumns: columns.filter((c) => !c.dbGenerated),
+            customFields,
+            identity: {
+                ...(userId === undefined ? {} : { userId }),
+                ...(ip === undefined ? {} : { ip }),
+            },
+        },
+        adopted,
+    };
+}
+//# sourceMappingURL=physical.js.map

package/dist/model/types.d.ts

@@ -0,0 +1,92 @@
+import type { TableRef } from './identifiers.js';
+export type Dialect = 'postgres' | 'mysql' | 'mssql';
+export type IpMode = 'raw' | 'hash' | 'truncate';
+export type SqlValue = string | number | boolean | null;
+export type CustomValue = string | number | boolean | null;
+export type ScalarType = 'string' | 'integer' | 'number' | 'boolean';
+export type Role = 'timestamp' | 'consent' | 'pageVisited' | 'ip' | 'userId' | 'username' | 'email' | 'custom' | 'isFirstVisit' | 'id';
+export type LogicalType = {
+    readonly kind: 'id';
+} | {
+    readonly kind: 'timestamp';
+} | {
+    readonly kind: 'boolean';
+} | {
+    readonly kind: 'string';
+    readonly maxLength: number;
+} | {
+    readonly kind: 'integer';
+} | {
+    readonly kind: 'number';
+} | {
+    readonly kind: 'json';
+};
+export interface ColumnDef {
+    readonly role: Role | 'promoted' | 'extra';
+    /** Role name, custom field name, or extra column name. */
+    readonly key: string;
+    /** Physical column name, already validated against the identifier pattern. */
+    readonly name: string;
+    readonly type: LogicalType;
+    readonly nullable: boolean;
+    /** Drives consent stripping, SQL comments and grant comments. */
+    readonly personal: boolean;
+    /** True only for `id`: never inserted. */
+    readonly dbGenerated: boolean;
+    /** The real database type, lower-case (`timestamptz`, `int2`, ...). Set after the catalog was read (startup), never from config. */
+    readonly physicalType?: string;
+}
+export interface CustomFieldDef {
+    type: ScalarType;
+    maxLength?: number;
+    personal?: boolean;
+    column?: true | string;
+    breakdown?: boolean;
+    /** Keep this (non-personal) field on rows where consent was denied. Default false: denied rows store nothing else. */
+    keepWhenDenied?: boolean;
+}
+export interface ResolvedCustomField {
+    readonly key: string;
+    readonly type: ScalarType;
+    readonly maxLength: number;
+    readonly personal: boolean;
+    readonly breakdown: boolean;
+    readonly keepWhenDenied: boolean;
+    /** Present when the field is promoted to its own column. */
+    readonly column?: ColumnDef;
+}
+/** The part of the config that decides table shape. No secrets, no functions: safe to read from JSON. */
+export interface SchemaConfig {
+    table: string | {
+        database?: string;
+        schema?: string;
+        name: string;
+    };
+    tableMode?: 'recommended' | 'existing';
+    columns?: Partial<Record<Role, string | false>>;
+    customFields?: Record<string, CustomFieldDef>;
+    page?: {
+        maxLength?: number;
+    };
+    firstVisit?: {
+        enabled?: boolean;
+    };
+}
+export interface ColumnModel {
+    readonly table: TableRef;
+    readonly mode: 'recommended' | 'existing';
+    /** Mapped columns, in DDL order. */
+    readonly columns: readonly ColumnDef[];
+    /** `columns` minus database-generated ones, in insert order. */
+    readonly insertColumns: readonly ColumnDef[];
+    /** Optional roles that are not stored; drives the startup info log. */
+    readonly unmappedRoles: readonly Role[];
+    readonly customFields: ReadonlyMap<string, ResolvedCustomField>;
+    readonly identity: {
+        readonly userId?: ColumnDef;
+        readonly ip?: ColumnDef;
+    };
+    readonly firstVisitEnabled: boolean;
+}
+export declare const OPTIONAL_STORED_ROLES: readonly Role[];
+//# sourceMappingURL=types.d.ts.map

package/dist/model/types.js

@@ -0,0 +1,9 @@
+export const OPTIONAL_STORED_ROLES = [
+    'ip',
+    'userId',
+    'username',
+    'email',
+    'custom',
+    'id',
+];
+//# sourceMappingURL=types.js.map

package/dist/protocol.d.ts

@@ -0,0 +1,222 @@
+export type Interval = 'hour' | 'day' | 'week' | 'month';
+export type ErrorCode = 'forbidden' | 'not_found' | 'method_not_allowed' | 'invalid_parameter' | 'range_too_large' | 'invalid_query' | 'timeout' | 'unavailable' | 'internal';
+export type UnavailableReason = 'no_identity_column' | 'identity_not_reliable' | 'disabled_by_host' | 'column_not_mapped';
+export interface Unavailable {
+    reason: UnavailableReason;
+    message: string;
+}
+export interface ResponseMeta {
+    generatedAt: string;
+    from?: string;
+    to?: string;
+    interval?: Interval;
+    piiMasked: boolean;
+    cached: boolean;
+}
+/** Why an explorer query was refused (spec 18.4). The message for each is a fixed sentence. */
+export type QueryErrorReason = 'too_long' | 'too_many_clauses' | 'unbalanced_quote' | 'empty_value' | 'value_too_long' | 'unknown_field' | 'bad_value';
+export interface ApiErrorBody {
+    code: ErrorCode;
+    message: string;
+    param?: string;
+    /** Only for `invalid_query`. */
+    reason?: QueryErrorReason;
+    /** Only for `invalid_query`: 0-based character offset in `q`. */
+    position?: number;
+}
+export type ApiResponse<T> = {
+    success: true;
+    data: T;
+    unavailable: null;
+    error: null;
+    meta: ResponseMeta;
+} | {
+    success: true;
+    data: null;
+    unavailable: Unavailable;
+    error: null;
+    meta: ResponseMeta;
+} | {
+    success: false;
+    data: null;
+    unavailable: null;
+    error: ApiErrorBody;
+};
+export type WidgetAvailability = {
+    available: true;
+} | {
+    available: false;
+    reason: UnavailableReason;
+    message: string;
+};
+export type NewVsReturningSource = 'computed' | 'column';
+export type NewVsReturningBasis = 'user_id' | 'ip' | 'user_id_then_ip';
+export type NewVsReturningAvailability = {
+    available: true;
+    source: NewVsReturningSource;
+    basis: NewVsReturningBasis;
+    approximate: boolean;
+} | {
+    available: false;
+    reason: UnavailableReason;
+    message: string;
+};
+export interface Breakdown {
+    key: string;
+    label: string;
+}
+export interface MetaData {
+    version: 2;
+    now: string;
+    intervals: readonly Interval[];
+    limits: {
+        maxRangeDays: number;
+        maxBuckets: number;
+        topPagesMax: number;
+        recentMax: number;
+        newVsReturningMaxRangeDays: number;
+    };
+    defaults: {
+        rangeDays: number;
+        interval: Interval;
+        topPagesLimit: number;
+        recentLimit: number;
+    };
+    breakdowns: readonly Breakdown[];
+    widgets: {
+        visitsOverTime: WidgetAvailability;
+        topPages: WidgetAvailability;
+        consentRate: WidgetAvailability;
+        newVsReturning: NewVsReturningAvailability;
+        recentVisits: WidgetAvailability;
+        /** v0.6. Absent from older servers: treat a missing key as unavailable. */
+        explorer?: WidgetAvailability;
+    };
+    /** v0.6 (spec 18.1). Absent when the explorer is disabled or the server predates it. */
+    explorer?: ExplorerMeta;
+    fields: {
+        id: boolean;
+        ipAddress: boolean;
+        userId: boolean;
+        username: boolean;
+        email: boolean;
+        isFirstVisit: boolean;
+    };
+    features: {
+        recentVisitsCursor: boolean;
+        piiRevealable: boolean;
+    };
+}
+export interface VisitPoint {
+    bucket: string;
+    visits: number;
+}
+export interface BreakdownSeries {
+    value: string | null;
+    isOther: boolean;
+    points: readonly VisitPoint[];
+}
+export interface VisitsOverTimeData {
+    interval: Interval;
+    points: readonly VisitPoint[];
+    total: number;
+    breakdown?: {
+        key: string;
+        series: readonly BreakdownSeries[];
+    };
+}
+export interface TopPage {
+    page: string;
+    visits: number;
+    share: number;
+}
+export interface TopPagesData {
+    totalVisits: number;
+    pages: readonly TopPage[];
+    otherVisits: number;
+}
+export interface NewVsReturningCounts {
+    new: number;
+    returning: number;
+    unknown: number;
+}
+export interface NewVsReturningData {
+    interval: Interval;
+    source: NewVsReturningSource;
+    basis: NewVsReturningBasis;
+    approximate: boolean;
+    points: readonly (NewVsReturningCounts & {
+        bucket: string;
+    })[];
+    totals: NewVsReturningCounts;
+}
+export interface ConsentCounts {
+    granted: number;
+    denied: number;
+    rate: number | null;
+}
+export interface ConsentRateData {
+    interval: Interval;
+    points: readonly (ConsentCounts & {
+        bucket: string;
+    })[];
+    totals: ConsentCounts;
+}
+export interface RecentVisit {
+    id: string | null;
+    timestamp: string;
+    pageVisited: string;
+    consent: boolean;
+    isFirstVisit: boolean | null;
+    ipAddress: string | null;
+    userId: string | null;
+    username: string | null;
+    email: string | null;
+    custom: Readonly<Record<string, string | number | boolean | null>> | null;
+}
+export interface RecentVisitsData {
+    visits: readonly RecentVisit[];
+    nextCursor: string | null;
+}
+export type SearchFieldType = 'text' | 'boolean' | 'number';
+export interface SearchFieldInfo {
+    key: string;
+    type: SearchFieldType;
+    /** Bare terms (no `key:`) match this field. */
+    search: boolean;
+    /** Shown in the field sidebar and usable as `split`. */
+    facet: boolean;
+}
+export interface ExplorerMeta {
+    fields: readonly SearchFieldInfo[];
+    limits: {
+        maxQueryChars: number;
+        maxClauses: number;
+        maxValueChars: number;
+        maxRangeDays: number;
+        facetTop: number;
+        tailMinIntervalMs: number;
+    };
+}
+export interface SearchData {
+    visits: readonly RecentVisit[];
+    nextCursor: string | null;
+    matched: number;
+}
+/** Same shape as visits-over-time; `breakdown` holds the split series when `split` was given. */
+export type SearchHistogramData = VisitsOverTimeData;
+export interface FacetValue {
+    value: string;
+    count: number;
+}
+export interface FieldFacet {
+    key: string;
+    values: readonly FacetValue[];
+    nullCount: number;
+    otherCount: number;
+}
+export interface SearchFieldsData {
+    matched: number;
+    fields: readonly FieldFacet[];
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -0,0 +1,5 @@
+// Wire types of the dynalitics read API (docs/SPEC.md section 10, v0.2). Types only.
+// This file is a vendored copy of packages/dynalitics/src/protocol.ts; the dashboard must not
+// depend on the server package. `npm run check:protocol -w dynalitics-dashboard` diffs the two.
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/queue/pipeline.d.ts

@@ -0,0 +1,46 @@
+import type { SqlDialect } from '../dialect/types.js';
+import { type Driver } from '../driver/types.js';
+import type { ColumnModel, SqlValue } from '../model/types.js';
+import type { Identity } from '../track/build-row.js';
+import type { FirstVisit } from '../track/first-visit.js';
+import type { ResolvedConfig } from '../config/schema.js';
+import type { ErrorInfo, FlushResult, TrackResult } from '../types.js';
+export interface QueuedRow {
+    readonly values: readonly SqlValue[];
+    readonly identity: Identity | null;
+}
+export interface PipelineDeps {
+    readonly driver: Driver;
+    readonly dialect: SqlDialect;
+    readonly model: ColumnModel;
+    readonly queue: ResolvedConfig['queue'];
+    readonly firstVisit: FirstVisit | undefined;
+    readonly report: (info: ErrorInfo) => void;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly random: () => number;
+    readonly now: () => number;
+    readonly requestTimeoutMs: number;
+}
+export interface PipelineStats {
+    queued: number;
+    written: number;
+    failed: number;
+    droppedFull: number;
+    queueLength: number;
+}
+export interface Pipeline {
+    enqueue(row: QueuedRow): Promise<TrackResult>;
+    flush(opts?: {
+        timeoutMs?: number;
+    }): Promise<FlushResult>;
+    close(opts?: {
+        timeoutMs?: number;
+    }): Promise<FlushResult>;
+    stats(): PipelineStats;
+}
+/**
+ * Bounded in-memory queue with batched multi-row INSERTs (spec 9). One batch is in flight at a time, so write-time
+ * first-visit resolution is race-free within one process.
+ */
+export declare function createPipeline(deps: PipelineDeps): Pipeline;
+//# sourceMappingURL=pipeline.d.ts.map