@biref/scanner 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1004,6 +1004,21 @@ declare class QueryPlanExecutor {
     private static filterKeys;
 }
 
+/**
+ * A single query that would be executed by `findMany` / `findFirst`.
+ *
+ * `sql` is the parameterized SQL string, `params` are the bound values,
+ * and `entity` identifies which table the query targets. For include
+ * trees the `includes` array contains one `ExplainedQuery` per nested
+ * level, mirroring the execution order.
+ */
+interface ExplainedQuery {
+    readonly entity: string;
+    readonly sql: string;
+    readonly params: readonly unknown[];
+    readonly includes: readonly ExplainedQuery[];
+}
+
 /**
  * Runtime context threaded through every `ChainBuilder` instance.
  *
@@ -1071,6 +1086,22 @@ declare class ChainBuilder {
     include(relationName: string, build?: (q: ChainBuilder) => ChainBuilder): ChainBuilder;
     findMany(): Promise<readonly ParsedRecord[]>;
     findFirst(): Promise<ParsedRecord | null>;
+    /**
+     * Build and return every SQL query that `findMany` would execute,
+     * without running them. Walks the full plan tree including nested
+     * includes, returning the root query and one child per include level.
+     *
+     * Include children use placeholder `IN (?)` filters since the real
+     * parent key values are only known at execution time.
+     *
+     * Accepts a `QueryEngine` to produce adapter-specific SQL. Pass the
+     * adapter's engine for the dialect you want to inspect:
+     *
+     *   const explained = chain.toSQL(biref.adapters.get('postgres').engine);
+     */
+    toSQL(engine: QueryEngine): ExplainedQuery;
+    private static explainPlan;
+    private static buildExplainChildPlan;
     /**
      * Escape hatch for advanced callers (tests, tooling): exposes the
      * accumulated plan without executing it. The typed builder's public
@@ -1350,6 +1381,16 @@ interface TypedChain<S extends BirefSchemaShape, Ns extends keyof S, E extends k
     }>;
     findMany(): Promise<readonly HydratedRow<Sel, Inc>[]>;
     findFirst(): Promise<HydratedRow<Sel, Inc> | null>;
+    /**
+     * Build and return every SQL query that `findMany` would execute,
+     * without running them. Walks the full plan tree including nested
+     * includes.
+     *
+     * Pass the adapter's engine for the dialect you want to inspect:
+     *
+     *   chain.toSQL(biref.adapters.get('postgres').engine)
+     */
+    toSQL(engine: QueryEngine): ExplainedQuery;
     toPlan(): QueryPlan;
 }
 /**
@@ -1646,4 +1687,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, 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 };
+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 ExplainedQuery, 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 };

package/dist/index.d.ts

@@ -1004,6 +1004,21 @@ declare class QueryPlanExecutor {
     private static filterKeys;
 }
 
+/**
+ * A single query that would be executed by `findMany` / `findFirst`.
+ *
+ * `sql` is the parameterized SQL string, `params` are the bound values,
+ * and `entity` identifies which table the query targets. For include
+ * trees the `includes` array contains one `ExplainedQuery` per nested
+ * level, mirroring the execution order.
+ */
+interface ExplainedQuery {
+    readonly entity: string;
+    readonly sql: string;
+    readonly params: readonly unknown[];
+    readonly includes: readonly ExplainedQuery[];
+}
+
 /**
  * Runtime context threaded through every `ChainBuilder` instance.
  *
@@ -1071,6 +1086,22 @@ declare class ChainBuilder {
     include(relationName: string, build?: (q: ChainBuilder) => ChainBuilder): ChainBuilder;
     findMany(): Promise<readonly ParsedRecord[]>;
     findFirst(): Promise<ParsedRecord | null>;
+    /**
+     * Build and return every SQL query that `findMany` would execute,
+     * without running them. Walks the full plan tree including nested
+     * includes, returning the root query and one child per include level.
+     *
+     * Include children use placeholder `IN (?)` filters since the real
+     * parent key values are only known at execution time.
+     *
+     * Accepts a `QueryEngine` to produce adapter-specific SQL. Pass the
+     * adapter's engine for the dialect you want to inspect:
+     *
+     *   const explained = chain.toSQL(biref.adapters.get('postgres').engine);
+     */
+    toSQL(engine: QueryEngine): ExplainedQuery;
+    private static explainPlan;
+    private static buildExplainChildPlan;
     /**
      * Escape hatch for advanced callers (tests, tooling): exposes the
      * accumulated plan without executing it. The typed builder's public
@@ -1350,6 +1381,16 @@ interface TypedChain<S extends BirefSchemaShape, Ns extends keyof S, E extends k
     }>;
     findMany(): Promise<readonly HydratedRow<Sel, Inc>[]>;
     findFirst(): Promise<HydratedRow<Sel, Inc> | null>;
+    /**
+     * Build and return every SQL query that `findMany` would execute,
+     * without running them. Walks the full plan tree including nested
+     * includes.
+     *
+     * Pass the adapter's engine for the dialect you want to inspect:
+     *
+     *   chain.toSQL(biref.adapters.get('postgres').engine)
+     */
+    toSQL(engine: QueryEngine): ExplainedQuery;
     toPlan(): QueryPlan;
 }
 /**
@@ -1646,4 +1687,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, 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 };
+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 ExplainedQuery, 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 };

package/dist/index.js

@@ -2849,6 +2849,50 @@ var ChainBuilder = class _ChainBuilder {
     const rows = await this.ctx.executor.execute(limited, this.ctx.model);
     return rows[0] ?? null;
   }
+  /**
+   * Build and return every SQL query that `findMany` would execute,
+   * without running them. Walks the full plan tree including nested
+   * includes, returning the root query and one child per include level.
+   *
+   * Include children use placeholder `IN (?)` filters since the real
+   * parent key values are only known at execution time.
+   *
+   * Accepts a `QueryEngine` to produce adapter-specific SQL. Pass the
+   * adapter's engine for the dialect you want to inspect:
+   *
+   *   const explained = chain.toSQL(biref.adapters.get('postgres').engine);
+   */
+  toSQL(engine) {
+    return _ChainBuilder.explainPlan(this.plan, engine, this.ctx.model);
+  }
+  static explainPlan(plan, engine, model) {
+    const built = engine.build(plan.spec, model);
+    const childExplained = [];
+    for (const include of plan.includes) {
+      const childPlan = _ChainBuilder.buildExplainChildPlan(include);
+      childExplained.push(_ChainBuilder.explainPlan(childPlan, engine, model));
+    }
+    return {
+      entity: `${plan.spec.namespace}.${plan.spec.entity}`,
+      sql: built.command,
+      params: built.params,
+      includes: childExplained
+    };
+  }
+  static buildExplainChildPlan(include) {
+    const filters = [...include.plan.spec.filters ?? []];
+    for (const childKey of include.childKeys) {
+      filters.push({
+        field: childKey,
+        operator: "in",
+        value: ["?"]
+      });
+    }
+    return {
+      ...include.plan,
+      spec: { ...include.plan.spec, filters }
+    };
+  }
   /**
    * Escape hatch for advanced callers (tests, tooling): exposes the
    * accumulated plan without executing it. The typed builder's public