@biref/scanner 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -1,23 +1,20 @@
 /**
- * Structural type for the database client the Postgres adapter consumes.
+ * Structural type for the database client the MySQL adapter consumes.
  *
- * Declares a single `query` method that takes a SQL string plus
- * optional parameters and returns an object with a `rows` array.
- * `pg.Client`, `pg.Pool`, and any structurally compatible library
- * satisfy the shape without the SDK importing `pg`.
+ * Declares a single `execute` method that takes a SQL string plus
+ * optional parameters and returns a tuple of `[rows, fields]`.
+ * `mysql2/promise` Connection, Pool, and any structurally compatible
+ * library satisfy the shape without the SDK importing `mysql2`.
  *
  * @example
  * ```ts
- * import pg from 'pg';
- * const client = new pg.Client({ ... });
- * await client.connect();
- * postgresAdapter.create(client);
+ * import mysql from 'mysql2/promise';
+ * const connection = await mysql.createConnection({ ... });
+ * mysqlAdapter.create(connection);
  * ```
  */
-interface PostgresClient {
-    query<TRow = unknown>(text: string, params?: readonly unknown[]): Promise<{
-        rows: TRow[];
-    }>;
+interface MySQLClient {
+    execute<TRow = unknown>(sql: string, params?: readonly unknown[]): Promise<[TRow[], unknown]>;
 }
 
 /**
@@ -325,46 +322,46 @@ interface IntrospectOptions {
 }
 
 /**
- * Postgres implementation of the `Introspector` port.
+ * MySQL implementation of the `Introspector` port.
  *
- * Runs six queries against `pg_catalog` in parallel (tables, columns,
- * primary keys, foreign keys, indexes, constraints) and hands the
- * result to `EntityAssembler`, which stitches them into a paradigm-
+ * Runs six queries against `information_schema` in parallel (tables,
+ * columns, primary keys, foreign keys, indexes, constraints) and hands
+ * the result to `EntityAssembler`, which stitches them into a paradigm-
  * neutral `DataModel`.
  *
  * What it returns for each entity:
  *   - fields with normalized type categories
  *   - identifier (primary key columns)
  *   - relationships in BOTH directions
- *   - constraints (unique, check, exclusion)
+ *   - constraints (unique, check)
  *   - indexes (excluding the primary key index)
  *
- * Accepts any client that satisfies `PostgresClient`, so it works with
- * `pg.Client`, `pg.Pool`, or any compatible library without the SDK
- * importing `pg`.
+ * Accepts any client that satisfies `MySQLClient`, so it works with
+ * `mysql2/promise` Connection, Pool, or any compatible library without
+ * the SDK importing `mysql2`.
  */
-declare class PostgresIntrospector implements Introspector {
+declare class MySQLIntrospector implements Introspector {
     private readonly client;
-    readonly name = "postgres";
+    readonly name = "mysql";
     readonly kind: "relational";
-    constructor(client: PostgresClient);
+    constructor(client: MySQLClient);
     introspect(options?: IntrospectOptions): Promise<DataModel>;
     private resolveNamespaces;
-    private static readonly ALL_NAMESPACES_SQL;
+    private currentDatabase;
+    private static readonly ALL_SCHEMAS_SQL;
     private static applyEntityFilters;
 }
 
 /**
- * Adapter metadata constants for Postgres.
+ * Adapter metadata constants for MySQL.
  *
  * Centralized so the rest of the adapter never references the literal
- * string 'postgres' or the URL schemes by hand. Anywhere those values
- * are needed, import the constant.
+ * string 'mysql' or the URL schemes by hand.
  */
-declare const POSTGRES_ADAPTER_NAME = "postgres";
-/** Literal type for the Postgres adapter name, used for discrimination. */
-type PostgresAdapterName = typeof POSTGRES_ADAPTER_NAME;
-declare const POSTGRES_URL_SCHEMES: readonly string[];
+declare const MYSQL_ADAPTER_NAME = "mysql";
+/** Literal type for the MySQL adapter name, used for discrimination. */
+type MySQLAdapterName = typeof MYSQL_ADAPTER_NAME;
+declare const MYSQL_URL_SCHEMES: readonly string[];
 
 /**
  * Output of `QueryEngine.build`.
@@ -447,22 +444,21 @@ interface QueryEngine<TCommand = unknown> {
 }
 
 /**
- * Postgres implementation of the `QueryEngine` port.
+ * MySQL implementation of the `QueryEngine` port.
  *
- * Produces parameterized SQL using `$1`, `$2`, ... placeholders and
- * double-quoted identifiers. Validates the spec against the
- * `DataModel` before emitting any SQL: unknown entities or fields
- * throw rather than yielding a broken query.
+ * Produces parameterized SQL using `?` placeholders and backtick-quoted
+ * identifiers. Validates the spec against the `DataModel` before
+ * emitting any SQL: unknown entities or fields throw rather than
+ * yielding a broken query.
  *
  * Scope:
  *   - SELECT against a single entity
  *   - WHERE filters (every `FilterOperator`)
  *   - ORDER BY
  *   - LIMIT and OFFSET
- *   - No joins, group by, or aggregates yet
  */
-declare class PostgresQueryEngine implements QueryEngine<string> {
-    readonly name = "postgres";
+declare class MySQLQueryEngine implements QueryEngine<string> {
+    readonly name = "mysql";
     readonly kind: "relational";
     build(spec: QuerySpec, model: DataModel): BuiltQuery<string>;
 }
@@ -531,26 +527,27 @@ declare class DefaultRecordParser implements RecordParser {
 }
 
 /**
- * Postgres-aware `RecordParser`.
+ * MySQL-aware `RecordParser`.
  *
- * Extends `DefaultRecordParser` with behavior that matches how the
- * `pg` driver returns Postgres values:
+ * Extends `DefaultRecordParser` with behavior that matches how `mysql2`
+ * returns MySQL values:
  *
- *   - `int8` / `bigint` columns are returned by `pg` as strings by
- *     default (to preserve precision). This parser converts them to
- *     JS `bigint` so downstream code does not silently lose digits.
+ *   - `bigint` columns are returned by `mysql2` as strings by default
+ *     (unless `supportBigNumbers` + `bigNumberStrings` are configured).
+ *     This parser converts them to JS `bigint`.
  *
- *   - `json` / `jsonb` columns are usually already parsed by `pg`,
- *     but when they arrive as strings (for example from drivers that
- *     do not auto-parse) this parser parses them.
+ *   - `tinyint(1)` columns (category `boolean`) may arrive as `0`/`1`
+ *     numbers. This parser normalizes them to JS `boolean`.
  *
- *   - All other categories fall through to `DefaultRecordParser`.
+ *   - `json` columns may arrive as strings depending on driver config.
+ *     This parser parses them when needed.
  *
- * Use this parser when consuming rows that come from a `pg.Client` or
- * `pg.Pool`. For adapters that handle these concerns themselves, the
- * default parser is still appropriate.
+ *   - `decimal` columns are returned as strings by `mysql2` to
+ *     preserve precision. Passed through as-is.
+ *
+ *   - All other categories fall through to `DefaultRecordParser`.
  */
-declare class PostgresRecordParser extends DefaultRecordParser {
+declare class MySQLRecordParser extends DefaultRecordParser {
     protected coerce(field: Field, raw: unknown): ParsedValue;
 }
 
@@ -582,7 +579,7 @@ interface RawQueryRunner {
  * adapters with any name; the type accepts arbitrary strings in
  * addition to the known ones (see `AdapterName`).
  */
-type KnownAdapterName = 'postgres';
+type KnownAdapterName = 'postgres' | 'mysql';
 /**
  * Adapter name type.
  *
@@ -684,6 +681,141 @@ interface AdapterFactory<TClient = unknown, TName extends AdapterName = AdapterN
     create(client: TClient): Adapter<TName>;
 }
 
+/**
+ * MySQL adapter factory.
+ *
+ * Implements `AdapterFactory<MySQLClient, MySQLAdapterName>`.
+ * `create` builds an `Adapter` bound to the user-provided client.
+ *
+ * @example
+ * ```ts
+ * import mysql from 'mysql2/promise';
+ * import { Biref, mysqlAdapter } from '@biref/scanner';
+ *
+ * const connection = await mysql.createConnection({ ... });
+ *
+ * const biref = Biref.builder()
+ *   .withAdapter(mysqlAdapter.create(connection))
+ *   .build();
+ *
+ * const model = await biref.scan();
+ * ```
+ */
+declare const mysqlAdapter: AdapterFactory<MySQLClient, MySQLAdapterName>;
+/**
+ * Type guard: narrows a generic `Adapter` to an `Adapter<MySQLAdapterName>`.
+ */
+declare function isMySQLAdapter(adapter: Adapter): adapter is Adapter<MySQLAdapterName>;
+
+/**
+ * Structural type for the database client the Postgres adapter consumes.
+ *
+ * Declares a single `query` method that takes a SQL string plus
+ * optional parameters and returns an object with a `rows` array.
+ * `pg.Client`, `pg.Pool`, and any structurally compatible library
+ * satisfy the shape without the SDK importing `pg`.
+ *
+ * @example
+ * ```ts
+ * import pg from 'pg';
+ * const client = new pg.Client({ ... });
+ * await client.connect();
+ * postgresAdapter.create(client);
+ * ```
+ */
+interface PostgresClient {
+    query<TRow = unknown>(text: string, params?: readonly unknown[]): Promise<{
+        rows: TRow[];
+    }>;
+}
+
+/**
+ * Postgres implementation of the `Introspector` port.
+ *
+ * Runs six queries against `pg_catalog` in parallel (tables, columns,
+ * primary keys, foreign keys, indexes, constraints) and hands the
+ * result to `EntityAssembler`, which stitches them into a paradigm-
+ * neutral `DataModel`.
+ *
+ * What it returns for each entity:
+ *   - fields with normalized type categories
+ *   - identifier (primary key columns)
+ *   - relationships in BOTH directions
+ *   - constraints (unique, check, exclusion)
+ *   - indexes (excluding the primary key index)
+ *
+ * Accepts any client that satisfies `PostgresClient`, so it works with
+ * `pg.Client`, `pg.Pool`, or any compatible library without the SDK
+ * importing `pg`.
+ */
+declare class PostgresIntrospector implements Introspector {
+    private readonly client;
+    readonly name = "postgres";
+    readonly kind: "relational";
+    constructor(client: PostgresClient);
+    introspect(options?: IntrospectOptions): Promise<DataModel>;
+    private resolveNamespaces;
+    private static readonly ALL_NAMESPACES_SQL;
+    private static applyEntityFilters;
+}
+
+/**
+ * Adapter metadata constants for Postgres.
+ *
+ * Centralized so the rest of the adapter never references the literal
+ * string 'postgres' or the URL schemes by hand. Anywhere those values
+ * are needed, import the constant.
+ */
+declare const POSTGRES_ADAPTER_NAME = "postgres";
+/** Literal type for the Postgres adapter name, used for discrimination. */
+type PostgresAdapterName = typeof POSTGRES_ADAPTER_NAME;
+declare const POSTGRES_URL_SCHEMES: readonly string[];
+
+/**
+ * Postgres implementation of the `QueryEngine` port.
+ *
+ * Produces parameterized SQL using `$1`, `$2`, ... placeholders and
+ * double-quoted identifiers. Validates the spec against the
+ * `DataModel` before emitting any SQL: unknown entities or fields
+ * throw rather than yielding a broken query.
+ *
+ * Scope:
+ *   - SELECT against a single entity
+ *   - WHERE filters (every `FilterOperator`)
+ *   - ORDER BY
+ *   - LIMIT and OFFSET
+ *   - No joins, group by, or aggregates yet
+ */
+declare class PostgresQueryEngine implements QueryEngine<string> {
+    readonly name = "postgres";
+    readonly kind: "relational";
+    build(spec: QuerySpec, model: DataModel): BuiltQuery<string>;
+}
+
+/**
+ * Postgres-aware `RecordParser`.
+ *
+ * Extends `DefaultRecordParser` with behavior that matches how the
+ * `pg` driver returns Postgres values:
+ *
+ *   - `int8` / `bigint` columns are returned by `pg` as strings by
+ *     default (to preserve precision). This parser converts them to
+ *     JS `bigint` so downstream code does not silently lose digits.
+ *
+ *   - `json` / `jsonb` columns are usually already parsed by `pg`,
+ *     but when they arrive as strings (for example from drivers that
+ *     do not auto-parse) this parser parses them.
+ *
+ *   - All other categories fall through to `DefaultRecordParser`.
+ *
+ * Use this parser when consuming rows that come from a `pg.Client` or
+ * `pg.Pool`. For adapters that handle these concerns themselves, the
+ * default parser is still appropriate.
+ */
+declare class PostgresRecordParser extends DefaultRecordParser {
+    protected coerce(field: Field, raw: unknown): ParsedValue;
+}
+
 /**
  * Postgres adapter factory.
  *
@@ -1078,9 +1210,12 @@ type DefaultSelect<S extends BirefSchemaShape, Ns extends keyof S, E extends key
 };
 /**
  * Narrowed selection from a `select('id', 'email')` call.
+ *
+ * The `Keys` tuple may include `'*'` from the overload union; it is
+ * excluded before projecting so only real field names appear.
  */
-type PickSelect<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], Keys extends readonly (keyof FieldsOf<S, Ns, E>)[]> = {
-    readonly [K in Keys[number]]: TypeOf<S, Ns, E, K>;
+type PickSelect<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], Keys extends readonly (keyof FieldsOf<S, Ns, E> | '*')[]> = {
+    readonly [K in Exclude<Keys[number], '*'> as K extends keyof FieldsOf<S, Ns, E> ? K : never]: TypeOf<S, Ns, E, K>;
 };
 /**
  * An accumulated include map on a chain builder. Each key is a
@@ -1152,20 +1287,27 @@ type NullaryOps = 'is-null' | 'is-not-null';
  */
 interface TypedChain<S extends BirefSchemaShape, Ns extends keyof S, E extends keyof S[Ns], Sel extends Selection = DefaultSelect<S, Ns, E>, Inc extends IncludeMap = Record<string, never>> {
     /**
-     * Narrow the projection to a specific set of field names. Each name
-     * must exist on the entity; unknowns throw at chain time.
+     * Zero-argument shorthand for the wildcard.
      */
-    select<const K extends readonly (keyof FieldsOf<S, Ns, E>)[]>(...fields: K): TypedChain<S, Ns, E, PickSelect<S, Ns, E, K>, Inc>;
+    select(): TypedChain<S, Ns, E, DefaultSelect<S, Ns, E>, Inc>;
     /**
      * Explicit wildcard: every field of the entity, same shape as
      * calling `findMany()` without `select` at all. Kept as a
      * discoverable sentinel so `.select('*')` reads clearly in code.
+     *
+     * Listed before the generic overload so TypeScript's overload
+     * resolver picks it for the literal `'*'` argument.
      */
     select(wildcard: '*'): TypedChain<S, Ns, E, DefaultSelect<S, Ns, E>, Inc>;
     /**
-     * Zero-argument shorthand for the wildcard.
+     * Narrow the projection to a specific set of field names. Each name
+     * must exist on the entity; unknowns throw at chain time.
+     *
+     * The union includes `'*'` so autocomplete surfaces the wildcard
+     * alongside real field names, but the overload above captures the
+     * `'*'` literal before this one fires.
      */
-    select(): TypedChain<S, Ns, E, DefaultSelect<S, Ns, E>, Inc>;
+    select<const K extends readonly (keyof FieldsOf<S, Ns, E> | '*')[]>(...fields: K): TypedChain<S, Ns, E, PickSelect<S, Ns, E, K>, Inc>;
     where<F extends keyof FieldsOf<S, Ns, E>, Op extends Exclude<OpsFor<CategoryOfField<S, Ns, E, F>>, NullaryOps>>(field: F, operator: Op, value: ValueFor<Op, TypeOf<S, Ns, E, F>>): TypedChain<S, Ns, E, Sel, Inc>;
     where<F extends keyof FieldsOf<S, Ns, E>>(field: F, operator: Extract<OpsFor<CategoryOfField<S, Ns, E, F>>, NullaryOps>): TypedChain<S, Ns, E, Sel, Inc>;
     orderBy<F extends keyof FieldsOf<S, Ns, E>>(field: F, direction?: 'asc' | 'desc'): TypedChain<S, Ns, E, Sel, Inc>;
@@ -1504,4 +1646,4 @@ type ApplySchemaOverrides<Raw extends BirefSchemaShape, Overrides extends BirefO
 };
 type ReplaceFieldTs<Field, NewTs> = Field extends SchemaFieldDescriptor<infer _OldTs, infer Nullable, infer Identifier, infer Category> ? SchemaFieldDescriptor<NewTs, Nullable, Identifier, Category> : Field;
 
-export { type Adapter, type AdapterFactory, type AdapterName, AdapterRegistry, type ApplySchemaOverrides, Biref, BirefBuilder, type BirefOverridesShape, type BirefSchemaShape, type BuiltQuery, type BuiltQueryMetadata, type CardinalityOf, type CategoryOf, type CategoryOfField, ChainBuilder, type ChainBuilderContext, type Constraint, type ConstraintKind, CsvFormatter, type CsvFormatterOptions, DataModel, DefaultRecordParser, type DefaultSelect, type EngineKind, type Entity, type EntityRef, type Field, type FieldType, type FieldTypeCategory, type FieldsOf, type Filter, type FilterOperator, type Formatter, type HydratedRow, type IncludeMap, type Index, type IndexKind, type IntrospectOptions, type Introspector, JsonFormatter, type JsonFormatterOptions, type KnownAdapterName, type NullaryOps, type OpsFor, type OrderBy, POSTGRES_ADAPTER_NAME, POSTGRES_URL_SCHEMES, type ParsedRecord, type ParsedValue, type PickSelect, type PostgresAdapterName, type PostgresClient, PostgresIntrospector, PostgresQueryEngine, PostgresRecordParser, type QueryEngine, type QueryInclude, type QueryPlan, QueryPlanExecutor, type QuerySpec, RawFormatter, type RawQueryRunner, type RecordParser, type Reference, type ReferentialAction, type RelationsOf, type RelationsOfEntity, type Relationship, type RelationshipDirection, Scanner, type SchemaEntityDescriptor, type SchemaFieldDescriptor, type SchemaFile, type SchemaNamespaceDescriptor, type SchemaRelationDescriptor, type Selection, type SerializeOptions, type Split, type TargetE, type TargetNs, type TypeOf, type TypedChain, type TypedQueryRoot, type UntypedQueryRoot, type ValueFor, type WrapForCardinality, generateSchema, generateSchemaFiles, isPostgresAdapter, overridesScaffold, postgresAdapter, tsTypeFor };
+export { type Adapter, type AdapterFactory, type AdapterName, AdapterRegistry, type ApplySchemaOverrides, Biref, BirefBuilder, type BirefOverridesShape, type BirefSchemaShape, type BuiltQuery, type BuiltQueryMetadata, type CardinalityOf, type CategoryOf, type CategoryOfField, ChainBuilder, type ChainBuilderContext, type Constraint, type ConstraintKind, CsvFormatter, type CsvFormatterOptions, DataModel, DefaultRecordParser, type DefaultSelect, type EngineKind, type Entity, type EntityRef, type Field, type FieldType, type FieldTypeCategory, type FieldsOf, type Filter, type FilterOperator, type Formatter, type HydratedRow, type IncludeMap, type Index, type IndexKind, type IntrospectOptions, type Introspector, JsonFormatter, type JsonFormatterOptions, type KnownAdapterName, MYSQL_ADAPTER_NAME, MYSQL_URL_SCHEMES, type MySQLAdapterName, type MySQLClient, MySQLIntrospector, MySQLQueryEngine, MySQLRecordParser, type NullaryOps, type OpsFor, type OrderBy, POSTGRES_ADAPTER_NAME, POSTGRES_URL_SCHEMES, type ParsedRecord, type ParsedValue, type PickSelect, type PostgresAdapterName, type PostgresClient, PostgresIntrospector, PostgresQueryEngine, PostgresRecordParser, type QueryEngine, type QueryInclude, type QueryPlan, QueryPlanExecutor, type QuerySpec, RawFormatter, type RawQueryRunner, type RecordParser, type Reference, type ReferentialAction, type RelationsOf, type RelationsOfEntity, type Relationship, type RelationshipDirection, Scanner, type SchemaEntityDescriptor, type SchemaFieldDescriptor, type SchemaFile, type SchemaNamespaceDescriptor, type SchemaRelationDescriptor, type Selection, type SerializeOptions, type Split, type TargetE, type TargetNs, type TypeOf, type TypedChain, type TypedQueryRoot, type UntypedQueryRoot, type ValueFor, type WrapForCardinality, generateSchema, generateSchemaFiles, isMySQLAdapter, isPostgresAdapter, mysqlAdapter, overridesScaffold, postgresAdapter, tsTypeFor };