@dbsp/core 1.8.0 → 1.10.0

package/dist/index.d.ts

@@ -1693,13 +1693,14 @@ declare class UnsupportedStrategyError extends Error {
  */
 declare class ModelIRImpl implements ModelIR {
     readonly tables: ReadonlyMap<string, TableIR>;
+    readonly externalTables: ReadonlySet<string>;
     readonly relations: ReadonlyMap<string, RelationIR>;
     readonly enums?: ReadonlyMap<string, EnumIR>;
     readonly extensions?: readonly string[];
     readonly sequences?: ReadonlyMap<string, SequenceIR>;
     private readonly relationsBySource;
     private readonly relationsByTarget;
-    constructor(tables: Map<string, TableIR>, relations: Map<string, RelationIR>, enums?: Map<string, EnumIR>, extensions?: readonly string[], sequences?: Map<string, SequenceIR>);
+    constructor(tables: Map<string, TableIR>, relations: Map<string, RelationIR>, enums?: Map<string, EnumIR>, extensions?: readonly string[], sequences?: Map<string, SequenceIR>, externalTables?: Iterable<string>);
     /**
      * Get table by name
      */
@@ -4074,8 +4075,14 @@ interface QueryBuilder<TResult = unknown> {
      * Check whether any matching rows exist.
      *
      * Compiles to `SELECT EXISTS(SELECT 1 FROM ... WHERE ...)`.
-     * Strips `orderBy` and `include` (irrelevant for existence checks).
-     * Preserves `groupBy`, `having`, and `offset` (they affect the result set).
+     * Strips `orderBy`; every include is kept and compiled exactly as for the
+     * full query — nothing is pruned. The `SELECT 1` wrap then discards the
+     * target list, so target-list hydration (the default `json_agg`) vanishes
+     * for free while FROM joins (`inner`/`left`/`lateral`/`cte`, incl. recursive)
+     * ride along and filter/multiply the root rows just as they would in the full
+     * query. `groupBy`, `having`, and `offset` are preserved (they affect the
+     * result). A recursive include therefore builds its CTE here (and throws on a
+     * dialect without `supportsRecursiveCTE`) rather than a cheaper shortcut.
      *
      * Requires `db` to be configured in createOrm() options.
      *
@@ -4461,7 +4468,10 @@ declare class QueryBuilderImpl<TResult = unknown> implements QueryBuilder<TResul
     private executeWithHooksInner;
     /**
      * Build an existence-check intent from current state.
-     * Strips orderBy and include (irrelevant), preserves groupBy/having/offset.
+     * Strips orderBy (irrelevant once wrapped in EXISTS), sets existsWrap and
+     * limit: 1, and keeps every include unchanged; the compiler decides which
+     * include contributions still need to be emitted (see exists-intent.ts
+     * and shouldEmitInclude() in the pgsql compiler) (#230).
      */
     private buildExistsIntent;
     /**
@@ -7455,6 +7465,19 @@ declare function defineModel<DB = Record<string, unknown>>(options: DefineModelO
  * - Custom logging frameworks (pino, winston, etc.)
  * - Structured logging
  */
+/**
+ * Category of a DX warning, used internally by {@link emitWarning} to decide
+ * env/per-instance suppression (#159). The category is NEVER passed to the
+ * logger sink (see {@link Logger.warn}) — it only drives the suppression
+ * decision inside `emitWarning`.
+ *
+ * - `'dx'`: developer-experience warnings (e.g. reserved word column access).
+ *   Suppressible via `DBSP_SUPPRESS_DX_WARNINGS` and per-instance `suppressDxWarnings`.
+ * - `'runtime'`: operational warnings (e.g. raw SQL usage). Suppressible via
+ *   its own gate (e.g. `NODE_ENV`) plus the global logger, but NOT via
+ *   `DBSP_SUPPRESS_DX_WARNINGS` or per-instance `suppressDxWarnings`.
+ */
+type WarningCategory = 'dx' | 'runtime';
 /**
  * Logger interface for dbsp library code.
  *
@@ -7465,6 +7488,13 @@ interface Logger {
     /**
      * Log a warning message.
      * Used for: reserved word usage, raw SQL warnings, deprecation notices.
+     *
+     * @param message - The warning message text (stable across versions —
+     *   downstream consumers may parse it). This is the ONLY argument the
+     *   sink ever receives — {@link WarningCategory} is internal to
+     *   {@link emitWarning}'s suppression decision and is never forwarded
+     *   here, so a `{ warn: console.warn }` or rest-arg/pino-style wrapper
+     *   never sees an unexpected extra token.
      */
     warn(message: string): void;
 }
@@ -7504,8 +7534,49 @@ declare function setLogger(logger: Logger): void;
 declare function getLogger(): Logger;
 /**
  * Reset logger to default (for testing).
+ *
+ * Also clears the module-level reserved-word warning dedup (#159) so tests
+ * that install a spy logger and assert on warn call counts stay isolated
+ * from each other.
  */
 declare function resetLogger(): void;
+/**
+ * Options for {@link emitWarning}.
+ */
+interface EmitWarningOptions {
+    /**
+     * Categories to suppress for this call site — e.g. an ORM instance's
+     * `suppressDxWarnings` option (passing `['dx']`). Union'd with the env gate: a warning is
+     * suppressed if EITHER applies.
+     */
+    readonly suppress?: readonly WarningCategory[];
+}
+/**
+ * Central warning emission helper (#159).
+ *
+ * Suppression precedence (a warning is suppressed if ANY of the following hold):
+ * 1. `category === 'dx'` AND `DBSP_SUPPRESS_DX_WARNINGS` is enabled per
+ *    {@link isEnvFlagEnabled} (read per-call, matching this repo's `NODE_ENV`
+ *    gate convention; `'0'`/`'false'` do NOT enable it).
+ * 2. `options.suppress` includes `category`.
+ * 3. The global logger is the exported `silentLogger` singleton (an explicit
+ *    global silence — checked by reference, not behavior, so a custom no-op
+ *    logger does NOT trigger this branch).
+ *
+ * Default (no env var, no `suppress` option, non-silent logger) → nothing is
+ * suppressed; the message reaches `getLogger().warn(...)`.
+ *
+ * The category is used ONLY for this suppression decision — it is NEVER
+ * passed to `getLogger().warn(...)`, which receives just the message (see
+ * {@link Logger.warn}).
+ *
+ * @returns `true` when the warning was actually emitted, `false` when
+ *   suppressed. Callers that dedup (e.g. the reserved-word warning) MUST
+ *   only record the dedup key when this returns `true` — recording it
+ *   unconditionally would let a suppressed call permanently "poison" the
+ *   dedup slot for every later, non-suppressed caller in the same process.
+ */
+declare function emitWarning(message: string, category: WarningCategory, options?: EmitWarningOptions): boolean;
 
 /** Error thrown when behavior = 'error' and unsupported feature detected */
 declare class UnsupportedFeatureError extends Error {
@@ -7628,6 +7699,24 @@ interface SimplifiedOrmOptions<T extends SchemaDefinition = SchemaDefinition> {
      * Pass FeatureBehaviorConfig for per-feature overrides.
      */
     readonly unsupportedFeatures?: UnsupportedFeatureBehavior | FeatureBehaviorConfig;
+    /**
+     * Suppress `'dx'` warnings (e.g. reserved-word column access) for this
+     * ORM instance (#159). Union'd with the `DBSP_SUPPRESS_DX_WARNINGS` env
+     * gate — a warning is suppressed if EITHER applies.
+     *
+     * Deliberately DX-only (not `WarningCategory[]`): `'runtime'` warnings
+     * (raw-SQL usage) are emitted by the adapter's compiler, which has no
+     * per-ORM-instance context, so a `'runtime'` entry here would silently
+     * do nothing. `'runtime'` warnings are controlled only by the adapter's
+     * `NODE_ENV` gate and the global logger (e.g. `silentLogger`) — not by
+     * `DBSP_SUPPRESS_DX_WARNINGS` or this option.
+     *
+     * @example
+     * ```typescript
+     * const orm = createOrm({ schema, adapter, suppressDxWarnings: true });
+     * ```
+     */
+    readonly suppressDxWarnings?: boolean;
 }
 /**
  * Create an ORM instance with the specified configuration.
@@ -8255,4 +8344,4 @@ declare const assertIntentHasOrderBy: (result: AssertionQueryResult, expected: b
  */
 declare function runAssertions(blocks: AssertionBlock[], results: AssertionQueryResult[], queries: string[], hasDb?: boolean): AssertionSummary;
 
-export { ASSERTION_TYPES, AdapterRequiredError, type AdjacencyOptions, type AfterMutationHook, type AfterQueryHook, type AggregateOptions, type AliasedColumn, type AliasedExprColumn, type AllColumns, AmbiguousPlanError, AmbiguousRelationError, type Assertion, type AssertionBlock, type AssertionOutcome, type AssertionQueryResult, type AssertionSummary, type AssertionType, BRAND, type BatchValuesOptions, type BatchValuesRef, type BeforeMutationHook, type BeforeQueryHook, type BrandKey, COLUMN_META, type CardinalityShorthand, CaseBuilder, type CaseValue, type ColumnDef, type ColumnMetaKey, ColumnNotFoundError, type ColumnRef, type ColumnSpec, type ColumnTypeToTS, CteBuilder, type CteDump, CteQueryBuilder, type CursorPaginateOptions, type CursorPaginatedResult, DEFAULT_CONVENTIONS, DEFAULT_FEATURE_CHECKERS, DUCKDB_CAPABILITIES, type DefaultFilters, type DefineModelOptions, DeleteBuilder, type DistinctField, type DumpMetaInput, type EdgeTableOptions, ErrorCode, type ErrorHookContext, Errors, ExecutionError, type ExprInput, ExpressionRef, type ExpressionSpec, type FeatureChecker, type FeatureUsage, type FilterOperators, type FilterValue, type FullTextSearchField, type FullTextSearchOptions, type GeneratedBelongsTo, type GeneratedColumn, type GeneratedColumnType, type GeneratedConventions, type GeneratedHasMany, type GeneratedHint, type GeneratedManyToMany, type GeneratedRelation, type GeneratedRelationKind, type GeneratedSchema, type GeneratedTable, type GetSchemaFromDbOptions, type HierarchyOptions, type HookErrorHandler, type HookManager, type HookPriority, type HydrateOptions, IRREGULAR_PLURALS, type IncludeOptions, type IncludeOptionsWithRecursive, type InferColumn, type InferColumnType, type InferColumnTypes, type InferDB, type InferDBFromSchema, type InferRefColumn, type InferRow, type InferRowType, type InferSchemaDB, type InferTableRow, type InferTables, type InferredRangeValue, InsertBuilder, IntentBuilder, type IntentBuilderState, type IntentSummary, InvalidOperationError, InvalidRelationDefinitionError, type JoinOptions, type JsonValue, type LightweightRelationsDef, type ListHierarchyOptions, type ListIndexOptions, type Logger, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, ModelIRImpl, type MutationDump, type MutationHookContext, type MutationOperation, NamingConventionMismatchError, type NegotiationResult, type NestedInclude, type SchemaColumnType$1 as NewSchemaColumnType, NotFoundError, type NqlBuilder, type NqlRawFragment, type NqlTag, type OnErrorHook, type OrderByInput, type OrderByRecord, type OrderBySpec, type OrmInstance, type OrmOf, type OrmOptions, type OrmOptionsWithAdapter, type OrmOptionsWithModel, type OrmOptionsWithSchema, POSTGRESQL_CAPABILITIES, type PaginateOptions, type PaginatedResult, type ParseError, type ParseResult, type ParsedRelationDef, type ParsedRelationKey, type PathOptions, type PrioritizedHook, type QueryAssertionResult, type QueryBuilder, type QueryHookContext, type QueryResultType, RELATION_META, type RangeType, RawCteQueryBuilder, type RecursiveDump, type RecursiveIncludeConfig, type RecursiveOptions, RecursiveShapeMismatchError, type RefDefinition, type RefOptions, type RelationHints, type RelationKey, type RelationMetaKey, RelationNotFoundError, type RelationObjectDef, type RelationPathIncludeNode, type RelationPathUsage, type RelationRef, type RelationShorthand, type RelationTupleDef, type ResolvedSchema, ResolvedSchemaValidation, ResultHydrator, SQLITE_CAPABILITIES, SQL_RAW_MARKER, type Schema, type SchemaBelongsToRelation, type SchemaCardinality, type SchemaColumnDefinition, type SchemaColumnType, type SchemaConfigInput, type SchemaConstraints, type SchemaConventionsDefinition, type SchemaConversionResult, type SchemaDefinition, type SchemaDefinitionInput, SchemaValidationError$1 as SchemaError, type SchemaExtras, type SchemaFilterStrategy, type SchemaForeignKeyReference, type SchemaHasManyRelation, type SchemaHintDefinition, type SchemaHintsDefinition, type SchemaIndexDefinition, type SchemaIndexOptions, type SchemaIndexesDefinition, type SchemaManyToManyRelation, type SchemaOnDeleteAction, type SchemaOptions, type SchemaRelationDefinition, type SchemaRelationKind, type SchemaRelationsDefinition, type SchemaTableDefinition, type SchemaTableOptions, type SchemaTablesDefinition, SchemaValidationError, type SelectField, type SelfRefRoles, type SetOperationBuilder, type SimplifiedOrmOptions, type SqlRawExpression, type StreamOptions, SubqueryBuilder, SubqueryExpression, TABLE_META, type TableAssertionData, type TableDDL, type TableDef, type TableIndexes, type TableMetaKey, TableNotFoundError, type TableRef, type TraversalDirection, UnhandledTypeInDialect, UnknownDialectError, UnsafeOperationError, UnsupportedCapabilityError, UnsupportedFeatureError, UnsupportedStrategyError, UpdateBuilder, UpsertBuilder, type ValidatedResolvedSchema, type WhereFilter, WindowBuilder, aggOrderBy, and, any, array, arrayAgg, assertCapability, assertContains, assertDbColumnExists, assertDbOutput, assertDbRowsEquals, assertDbRowsMax, assertDbRowsMin, assertDbValueEquals, assertEquals, assertIntentHasGroupBy, assertIntentHasOrderBy, assertIntentHasWhere, assertIntentTable, assertIntentType, assertIntentWith, assertMatches, assertParamsEquals, assertParamsLength, assertParamsType, assertParamsValue, assertResolvedSchemaToGeneratedSchema, assertSQLColumn, assertSQLEquals, assertSQLJoin, assertSQLTable, assertSuccess, assertTypeSupported, batchValues, buildModelFromResolvedSchema, buildModelFromSchema, capitalize, caseWhen, cast, coalesce, col, composeAfterMutationHooks, composeAfterQueryHooks, composeBeforeMutationHooks, composeBeforeQueryHooks, composeOnErrorHooks, countDistinctRelationPathsByName, createDialectCapabilities, createHookManager, createNqlTag, createOrm, createPseudoColumnMetadata, createRawCteBuilder, createRecursiveMetadata, decapitalize, defaultLogger, defineModel, defineSchema, denseRank, deriveRelationPathFromIntentPath, detectForeignKeys, detectManyToMany, distinct, eq, every, exists, ref as exprRef, extendDialect, extractPseudoColumnKeywords, findClosestMatch, fn, fullTextSearch, getAvailableDialects, getDialectCapabilities, getLogger, getRelationKind, getSchemaFromDb, gt, gte, inArray, inSubquery, inferForeignKey, inferRelationsFromSchema, isAliasedColumn, isAllColumns, isBatchValuesRef, isBelongsTo, isCardinalityShorthand, isColumnRef, isDistinctField, isDistinctFrom, isExpressionSpec, isGeneratedSchema, isHasMany, isKnownDialect, isManyToMany, isNotNull, isNull, isOverallSuccess, isRecursiveIncludeOptions, isRecursiveRelation, isRef, isRelationObjectDef, isRelationRef, isRelationTupleDef, isResolvedSchema, isSelfReferential, isSqlRaw, isSubqueryExpression, isTableRef, isWhereIntent, lag, lead, like, literal, lt, lte, namedArg, negotiateFeatures, neq, none, normalizeSQL, normalizeSchema, not, notExists, nqlRaw, objectToWhereIntent, op, or, outerRef, param, parseAssertionFile, parseRelationDef, parseRelationKey, pipeAfterMutationHooks, pipeAfterQueryHooks, pipeBeforeMutationHooks, pipeBeforeQueryHooks, pipeOnErrorHooks, plan, planRecursive, pluralize, rangeContainedBy, rangeContains, rangeOverlaps, rank, raw, rawExists, rawNotExists, ref$1 as ref, registerDialect, relationColumn, requiresDatabase, resetLogger, resolveQueryIndex, resolvedSchemaToGeneratedSchema, rowNumber, runAssertions, schema, schemaToModelIR, setLogger, silentLogger, singularize, some, sortByPriority, sql, star, stringAgg, subquery, supportsDDLGeneration, supportsExecution, supportsIntrospection, supportsRawSql, supportsStreaming, supportsTransactions, textScore, unary, validateAssertionBlocks, validateRecursiveInclude, validateRecursiveShape, validateTypeName, wAvg, wCount, wMax, wMin, wSum, withPriority };
+export { ASSERTION_TYPES, AdapterRequiredError, type AdjacencyOptions, type AfterMutationHook, type AfterQueryHook, type AggregateOptions, type AliasedColumn, type AliasedExprColumn, type AllColumns, AmbiguousPlanError, AmbiguousRelationError, type Assertion, type AssertionBlock, type AssertionOutcome, type AssertionQueryResult, type AssertionSummary, type AssertionType, BRAND, type BatchValuesOptions, type BatchValuesRef, type BeforeMutationHook, type BeforeQueryHook, type BrandKey, COLUMN_META, type CardinalityShorthand, CaseBuilder, type CaseValue, type ColumnDef, type ColumnMetaKey, ColumnNotFoundError, type ColumnRef, type ColumnSpec, type ColumnTypeToTS, CteBuilder, type CteDump, CteQueryBuilder, type CursorPaginateOptions, type CursorPaginatedResult, DEFAULT_CONVENTIONS, DEFAULT_FEATURE_CHECKERS, DUCKDB_CAPABILITIES, type DefaultFilters, type DefineModelOptions, DeleteBuilder, type DistinctField, type DumpMetaInput, type EdgeTableOptions, type EmitWarningOptions, ErrorCode, type ErrorHookContext, Errors, ExecutionError, type ExprInput, ExpressionRef, type ExpressionSpec, type FeatureChecker, type FeatureUsage, type FilterOperators, type FilterValue, type FullTextSearchField, type FullTextSearchOptions, type GeneratedBelongsTo, type GeneratedColumn, type GeneratedColumnType, type GeneratedConventions, type GeneratedHasMany, type GeneratedHint, type GeneratedManyToMany, type GeneratedRelation, type GeneratedRelationKind, type GeneratedSchema, type GeneratedTable, type GetSchemaFromDbOptions, type HierarchyOptions, type HookErrorHandler, type HookManager, type HookPriority, type HydrateOptions, IRREGULAR_PLURALS, type IncludeOptions, type IncludeOptionsWithRecursive, type InferColumn, type InferColumnType, type InferColumnTypes, type InferDB, type InferDBFromSchema, type InferRefColumn, type InferRow, type InferRowType, type InferSchemaDB, type InferTableRow, type InferTables, type InferredRangeValue, InsertBuilder, IntentBuilder, type IntentBuilderState, type IntentSummary, InvalidOperationError, InvalidRelationDefinitionError, type JoinOptions, type JsonValue, type LightweightRelationsDef, type ListHierarchyOptions, type ListIndexOptions, type Logger, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, ModelIRImpl, type MutationDump, type MutationHookContext, type MutationOperation, NamingConventionMismatchError, type NegotiationResult, type NestedInclude, type SchemaColumnType$1 as NewSchemaColumnType, NotFoundError, type NqlBuilder, type NqlRawFragment, type NqlTag, type OnErrorHook, type OrderByInput, type OrderByRecord, type OrderBySpec, type OrmInstance, type OrmOf, type OrmOptions, type OrmOptionsWithAdapter, type OrmOptionsWithModel, type OrmOptionsWithSchema, POSTGRESQL_CAPABILITIES, type PaginateOptions, type PaginatedResult, type ParseError, type ParseResult, type ParsedRelationDef, type ParsedRelationKey, type PathOptions, type PrioritizedHook, type QueryAssertionResult, type QueryBuilder, type QueryHookContext, type QueryResultType, RELATION_META, type RangeType, RawCteQueryBuilder, type RecursiveDump, type RecursiveIncludeConfig, type RecursiveOptions, RecursiveShapeMismatchError, type RefDefinition, type RefOptions, type RelationHints, type RelationKey, type RelationMetaKey, RelationNotFoundError, type RelationObjectDef, type RelationPathIncludeNode, type RelationPathUsage, type RelationRef, type RelationShorthand, type RelationTupleDef, type ResolvedSchema, ResolvedSchemaValidation, ResultHydrator, SQLITE_CAPABILITIES, SQL_RAW_MARKER, type Schema, type SchemaBelongsToRelation, type SchemaCardinality, type SchemaColumnDefinition, type SchemaColumnType, type SchemaConfigInput, type SchemaConstraints, type SchemaConventionsDefinition, type SchemaConversionResult, type SchemaDefinition, type SchemaDefinitionInput, SchemaValidationError$1 as SchemaError, type SchemaExtras, type SchemaFilterStrategy, type SchemaForeignKeyReference, type SchemaHasManyRelation, type SchemaHintDefinition, type SchemaHintsDefinition, type SchemaIndexDefinition, type SchemaIndexOptions, type SchemaIndexesDefinition, type SchemaManyToManyRelation, type SchemaOnDeleteAction, type SchemaOptions, type SchemaRelationDefinition, type SchemaRelationKind, type SchemaRelationsDefinition, type SchemaTableDefinition, type SchemaTableOptions, type SchemaTablesDefinition, SchemaValidationError, type SelectField, type SelfRefRoles, type SetOperationBuilder, type SimplifiedOrmOptions, type SqlRawExpression, type StreamOptions, SubqueryBuilder, SubqueryExpression, TABLE_META, type TableAssertionData, type TableDDL, type TableDef, type TableIndexes, type TableMetaKey, TableNotFoundError, type TableRef, type TraversalDirection, UnhandledTypeInDialect, UnknownDialectError, UnsafeOperationError, UnsupportedCapabilityError, UnsupportedFeatureError, UnsupportedStrategyError, UpdateBuilder, UpsertBuilder, type ValidatedResolvedSchema, type WarningCategory, type WhereFilter, WindowBuilder, aggOrderBy, and, any, array, arrayAgg, assertCapability, assertContains, assertDbColumnExists, assertDbOutput, assertDbRowsEquals, assertDbRowsMax, assertDbRowsMin, assertDbValueEquals, assertEquals, assertIntentHasGroupBy, assertIntentHasOrderBy, assertIntentHasWhere, assertIntentTable, assertIntentType, assertIntentWith, assertMatches, assertParamsEquals, assertParamsLength, assertParamsType, assertParamsValue, assertResolvedSchemaToGeneratedSchema, assertSQLColumn, assertSQLEquals, assertSQLJoin, assertSQLTable, assertSuccess, assertTypeSupported, batchValues, buildModelFromResolvedSchema, buildModelFromSchema, capitalize, caseWhen, cast, coalesce, col, composeAfterMutationHooks, composeAfterQueryHooks, composeBeforeMutationHooks, composeBeforeQueryHooks, composeOnErrorHooks, countDistinctRelationPathsByName, createDialectCapabilities, createHookManager, createNqlTag, createOrm, createPseudoColumnMetadata, createRawCteBuilder, createRecursiveMetadata, decapitalize, defaultLogger, defineModel, defineSchema, denseRank, deriveRelationPathFromIntentPath, detectForeignKeys, detectManyToMany, distinct, emitWarning, eq, every, exists, ref as exprRef, extendDialect, extractPseudoColumnKeywords, findClosestMatch, fn, fullTextSearch, getAvailableDialects, getDialectCapabilities, getLogger, getRelationKind, getSchemaFromDb, gt, gte, inArray, inSubquery, inferForeignKey, inferRelationsFromSchema, isAliasedColumn, isAllColumns, isBatchValuesRef, isBelongsTo, isCardinalityShorthand, isColumnRef, isDistinctField, isDistinctFrom, isExpressionSpec, isGeneratedSchema, isHasMany, isKnownDialect, isManyToMany, isNotNull, isNull, isOverallSuccess, isRecursiveIncludeOptions, isRecursiveRelation, isRef, isRelationObjectDef, isRelationRef, isRelationTupleDef, isResolvedSchema, isSelfReferential, isSqlRaw, isSubqueryExpression, isTableRef, isWhereIntent, lag, lead, like, literal, lt, lte, namedArg, negotiateFeatures, neq, none, normalizeSQL, normalizeSchema, not, notExists, nqlRaw, objectToWhereIntent, op, or, outerRef, param, parseAssertionFile, parseRelationDef, parseRelationKey, pipeAfterMutationHooks, pipeAfterQueryHooks, pipeBeforeMutationHooks, pipeBeforeQueryHooks, pipeOnErrorHooks, plan, planRecursive, pluralize, rangeContainedBy, rangeContains, rangeOverlaps, rank, raw, rawExists, rawNotExists, ref$1 as ref, registerDialect, relationColumn, requiresDatabase, resetLogger, resolveQueryIndex, resolvedSchemaToGeneratedSchema, rowNumber, runAssertions, schema, schemaToModelIR, setLogger, silentLogger, singularize, some, sortByPriority, sql, star, stringAgg, subquery, supportsDDLGeneration, supportsExecution, supportsIntrospection, supportsRawSql, supportsStreaming, supportsTransactions, textScore, unary, validateAssertionBlocks, validateRecursiveInclude, validateRecursiveShape, validateTypeName, wAvg, wCount, wMax, wMin, wSum, withPriority };

package/dist/index.js

@@ -60,6 +60,7 @@ import * as types_star from "@dbsp/types";
 // src/model-impl.ts
 var ModelIRImpl = class {
   tables;
+  externalTables;
   relations;
   enums;
   extensions;
@@ -67,8 +68,11 @@ var ModelIRImpl = class {
   // Pre-computed indexes for efficient lookups
   relationsBySource;
   relationsByTarget;
-  constructor(tables, relations, enums, extensions, sequences) {
+  constructor(tables, relations, enums, extensions, sequences, externalTables) {
     this.tables = Object.freeze(new Map(tables));
+    this.externalTables = Object.freeze(
+      new Set(externalTables)
+    );
     this.relations = Object.freeze(new Map(relations));
     if (enums) {
       this.enums = Object.freeze(new Map(enums));
@@ -156,6 +160,11 @@ var ModelIRImpl = class {
   validate() {
     const errors = [];
     for (const table of this.tables.values()) {
+      if (this.externalTables.has(table.name)) {
+        errors.push(
+          `Table "${table.name}" cannot be both managed and external`
+        );
+      }
       if (table.primaryKey) {
         const pkCols = Array.isArray(table.primaryKey) ? table.primaryKey : [table.primaryKey];
         for (const pk of pkCols) {
@@ -169,7 +178,7 @@ var ModelIRImpl = class {
     }
     for (const table of this.tables.values()) {
       for (const fk of table.foreignKeys) {
-        if (!this.tables.has(fk.references.table)) {
+        if (!this.tables.has(fk.references.table) && !this.externalTables.has(fk.references.table)) {
           errors.push(
             `Table "${table.name}" has FK referencing non-existent table "${fk.references.table}"`
           );
@@ -247,6 +256,28 @@ function getLogger() {
 }
 function resetLogger() {
   globalLogger = defaultLogger;
+  resetWarnedReservedWords();
+}
+function isEnvFlagEnabled(value) {
+  if (value === void 0) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+function emitWarning(message, category, options) {
+  if (category === "dx" && isEnvFlagEnabled(process.env.DBSP_SUPPRESS_DX_WARNINGS)) {
+    return false;
+  }
+  if (options?.suppress?.includes(category)) {
+    return false;
+  }
+  const logger = getLogger();
+  if (logger === silentLogger) {
+    return false;
+  }
+  logger.warn(message);
+  return true;
 }
 
 // src/dx/symbols.ts
@@ -306,10 +337,23 @@ var JS_RESERVED_WORDS = /* @__PURE__ */ new Set([
   "throw",
   "typeof"
 ]);
-function warnReservedWord(tableName, columnName) {
-  getLogger().warn(
-    `[dbsp] Warning: Column "${columnName}" in table "${tableName}" is a JavaScript reserved word. Access it via bracket notation: table['${columnName}']`
+var warnedReservedWords = /* @__PURE__ */ new Set();
+function resetWarnedReservedWords() {
+  warnedReservedWords.clear();
+}
+function warnReservedWord(tableName, columnName, suppress) {
+  const dedupKey = `${tableName}.${columnName}`;
+  if (warnedReservedWords.has(dedupKey)) {
+    return;
+  }
+  const emitted = emitWarning(
+    `[dbsp] Warning: Column "${columnName}" in table "${tableName}" is a JavaScript reserved word. Access it via bracket notation: table['${columnName}']`,
+    "dx",
+    suppress ? { suppress } : void 0
   );
+  if (emitted) {
+    warnedReservedWords.add(dedupKey);
+  }
 }
 function createColumnRef(tableName, columnName, relationPath) {
   const columnRef = {
@@ -439,7 +483,7 @@ function createRelationRef(targetTable, relationType, model, relationName, paren
     }
   });
 }
-function createTableRef(tableName, model) {
+function createTableRef(tableName, model, suppress) {
   const tableIR = model.getTable(tableName);
   if (!tableIR) {
     throw new Error(`Table "${tableName}" not found in model`);
@@ -463,7 +507,6 @@ function createTableRef(tableName, model) {
       relations.set(inverseName, { target: relation.source, type: "hasMany" });
     }
   }
-  const warnedReservedWords = /* @__PURE__ */ new Set();
   return new Proxy(base, {
     get(target, prop, receiver) {
       if (typeof prop === "symbol") {
@@ -478,10 +521,7 @@ function createTableRef(tableName, model) {
       const propStr = prop;
       if (JS_RESERVED_WORDS.has(propStr)) {
         if (hasColumn(tableIR.columns, propStr)) {
-          if (!warnedReservedWords.has(propStr)) {
-            warnReservedWord(tableName, propStr);
-            warnedReservedWords.add(propStr);
-          }
+          warnReservedWord(tableName, propStr, suppress);
           return createColumnRef(tableName, propStr);
         }
       }
@@ -532,9 +572,10 @@ function createTableRef(tableName, model) {
     }
   });
 }
-function createTablesProxy(model, tableNames) {
+function createTablesProxy(model, tableNames, options) {
   const tableSet = new Set(tableNames);
   const cache = /* @__PURE__ */ new Map();
+  const suppress = options?.suppressWarnings;
   return new Proxy(
     {},
     {
@@ -547,7 +588,7 @@ function createTablesProxy(model, tableNames) {
           return cache.get(propStr);
         }
         if (tableSet.has(propStr)) {
-          const tableRef = createTableRef(propStr, model);
+          const tableRef = createTableRef(propStr, model, suppress);
           cache.set(propStr, tableRef);
           return tableRef;
         }
@@ -566,7 +607,7 @@ function createTablesProxy(model, tableNames) {
         if (typeof prop === "string" && tableSet.has(prop)) {
           let tableRef = cache.get(prop);
           if (!tableRef) {
-            tableRef = createTableRef(prop, model);
+            tableRef = createTableRef(prop, model, suppress);
             cache.set(prop, tableRef);
           }
           return {
@@ -1234,6 +1275,7 @@ function addCompositeConstraintRelations(relations, tableNames, constraints) {
       const foreignKey = [...columns];
       const referencedKey = [...references];
       const belongsToName = deriveCompositeConstraintRelationName(
+        // biome-ignore lint/style/noNonNullAssertion: foreignKey copies columns whose length is guaranteed >= 1 by the "if (!columns?.length) continue;" guard above
         foreignKey[0],
         fkRef.options
       );
@@ -7735,6 +7777,13 @@ function findSelfRefRelation(model, table, direction) {
   return null;
 }
 
+// src/dx/exists-intent.ts
+function buildExistsIntent(baseIntent) {
+  const { orderBy: _orderBy, ...rest } = baseIntent;
+  const existsLimit = baseIntent.limit === 0 ? 0 : 1;
+  return { ...rest, existsWrap: true, limit: existsLimit };
+}
+
 // src/dx/pagination-impl.ts
 function resolveCursorKey(orderBy) {
   if (typeof orderBy === "string") return orderBy;
@@ -9765,36 +9814,20 @@ var QueryBuilderImpl = class _QueryBuilderImpl {
   }
   /**
    * Build an existence-check intent from current state.
-   * Strips orderBy and include (irrelevant), preserves groupBy/having/offset.
+   * Strips orderBy (irrelevant once wrapped in EXISTS), sets existsWrap and
+   * limit: 1, and keeps every include unchanged; the compiler decides which
+   * include contributions still need to be emitted (see exists-intent.ts
+   * and shouldEmitInclude() in the pgsql compiler) (#230).
    */
   buildExistsIntent() {
-    const baseIntent = this.buildIntent();
-    const {
-      orderBy: _orderBy,
-      include: _include,
-      ...rest
-    } = baseIntent;
-    return {
-      ...rest,
-      existsWrap: true,
-      limit: 1
-    };
+    return buildExistsIntent(this.buildIntent());
   }
   /**
    * Build exists-wrapped intent from a pre-built intent (E17b: for hook-aware path).
    * @internal
    */
   buildExistsIntentFromIntent(baseIntent) {
-    const {
-      orderBy: _orderBy,
-      include: _include,
-      ...rest
-    } = baseIntent;
-    return {
-      ...rest,
-      existsWrap: true,
-      limit: 1
-    };
+    return buildExistsIntent(baseIntent);
   }
   /**
    * Handle ambiguity based on strict mode setting.
@@ -10216,6 +10249,9 @@ function generateCreateIndexSQL(tableName, schemaName, opts) {
       `INCLUDE (${opts.include.map((c) => quoteIdent(c)).join(", ")})`
     );
   }
+  if (opts.unique && opts.nullsNotDistinct) {
+    parts.push("NULLS NOT DISTINCT");
+  }
   if (opts.with && Object.keys(opts.with).length > 0) {
     const withClauses = Object.entries(opts.with).map(([k, v2]) => `${k} = ${v2}`).join(", ");
     parts.push(`WITH (${withClauses})`);
@@ -10780,8 +10816,10 @@ function createOrm(options) {
     planOptions: globalPlanOptions,
     hooks: hookManager,
     onHookError,
-    unsupportedFeatures
+    unsupportedFeatures,
+    suppressDxWarnings
   } = options;
+  const suppressWarnings = suppressDxWarnings ? ["dx"] : void 0;
   let model;
   let schemaDefinition;
   let defaultFilters;
@@ -10815,7 +10853,11 @@ function createOrm(options) {
     }
   }
   const frozenHookStore = hookManager ? getHookStore(hookManager.freeze()) : void 0;
-  const tablesProxy = schemaObj && "tables" in schemaObj ? schemaObj.tables : createTablesProxy(model, model.tables ? [...model.tables.keys()] : []);
+  const tablesProxy = schemaObj && "tables" in schemaObj && !suppressWarnings ? schemaObj.tables : createTablesProxy(
+    model,
+    model.tables ? [...model.tables.keys()] : [],
+    suppressWarnings ? { suppressWarnings } : void 0
+  );
   return createOrmInstance(
     model,
     strictMode,
@@ -13071,6 +13113,7 @@ export {
   detectForeignKeys,
   detectManyToMany,
   distinct,
+  emitWarning,
   eq,
   every,
   exists,