@spooky-sync/query-builder 0.0.0-canary.1

package/src/repro_relationship.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { QueryBuilder, SchemaStructure } from './index';
+
+describe('QueryBuilder Relationship Inference', () => {
+  const schema = {
+    tables: [
+      {
+        name: 'game_database',
+        columns: {
+          id: { type: 'string', recordId: true, optional: false },
+          games: { type: 'string', optional: true },
+        },
+        primaryKey: ['id'],
+      },
+      {
+        name: 'game',
+        columns: {
+          id: { type: 'string', recordId: true, optional: false },
+          database: { type: 'string', recordId: true, optional: false },
+        },
+        primaryKey: ['id'],
+      },
+    ],
+    relationships: [
+      {
+        from: 'game_database',
+        field: 'games',
+        to: 'game',
+        cardinality: 'many',
+      },
+      {
+        from: 'game',
+        field: 'database',
+        to: 'game_database',
+        cardinality: 'one',
+      },
+    ],
+    backends: {},
+  } as const;
+
+  it('should correctly infer foreign key field for game_database -> games', () => {
+    const qb = new QueryBuilder(schema, 'game_database');
+
+    // We want to simulate: SELECT *, (SELECT * FROM game WHERE database=$parent.id) AS games FROM game_database
+    // This happens when we include 'games' in the related fields
+
+    // The QueryBuilder.related method adds to options.related
+    qb.related('games');
+
+    // To verify the generated subquery, we need to inspect the build output
+    // buildQueryFromOptions is internal, but we can check the result of build()
+    // or we can inspect the private options if we cast to any
+
+    const options = (qb as any).options;
+    expect(options.related).toHaveLength(1);
+    expect(options.related[0].alias).toBe('games');
+    expect(options.related[0].foreignKeyField).toBe('database');
+  });
+});

package/src/table-schema.ts

@@ -0,0 +1,268 @@
+/**
+ * Supported value types in the schema
+ */
+export type ValueType = 'string' | 'number' | 'boolean' | 'null' | 'json';
+
+/**
+ * Column metadata defining the type and optionality of a field
+ */
+export interface ColumnSchema {
+  readonly type: ValueType;
+  readonly optional: boolean;
+  readonly dateTime?: boolean;
+  readonly recordId?: boolean;
+}
+
+/**
+ * Table metadata containing columns and primary key information
+ */
+export interface TableSchemaMetadata {
+  readonly name: string;
+  readonly columns: {
+    readonly [columnName: string]: ColumnSchema;
+  };
+  readonly primaryKey: readonly string[];
+}
+
+/**
+ * Cardinality of a relationship: one-to-one or one-to-many
+ */
+export type Cardinality = 'one' | 'many';
+
+/**
+ * Relationship metadata defining how tables relate to each other
+ */
+export interface RelationshipMetadata {
+  readonly model: string;
+  readonly table: string;
+  readonly cardinality: Cardinality;
+}
+
+/**
+ * Complete schema metadata structure
+ * Maps table names to their schemas and relationships
+ */
+export interface SchemaMetadataStructure {
+  readonly tables: {
+    readonly [tableName: string]: TableSchemaMetadata;
+  };
+  readonly relationships: {
+    readonly [tableName: string]: {
+      readonly [fieldName: string]: RelationshipMetadata;
+    };
+  };
+}
+
+/**
+ * Type mapping from ValueType to TypeScript types
+ */
+export type TypeNameToTypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  null: null;
+  json: unknown;
+};
+
+/**
+ * Convert a column type to its TypeScript type
+ */
+export type ColumnToTSType<T extends ColumnSchema> = T extends {
+  optional: true;
+}
+  ? TypeNameToTypeMap[T['type']] | null
+  : TypeNameToTypeMap[T['type']];
+
+/**
+ * Helper to extract relationship field names for a table
+ */
+export type RelationshipFieldNames<
+  Metadata extends SchemaMetadataStructure,
+  TableName extends keyof Metadata['relationships'] & string,
+> = keyof Metadata['relationships'][TableName] & string;
+
+/**
+ * Helper to get cardinality for a specific relationship
+ */
+export type GetRelationshipCardinality<
+  Metadata extends SchemaMetadataStructure,
+  TableName extends keyof Metadata['relationships'] & string,
+  FieldName extends keyof Metadata['relationships'][TableName] & string,
+> = Metadata['relationships'][TableName][FieldName]['cardinality'];
+
+/**
+ * Helper to get related table name for a relationship
+ */
+export type GetRelatedTable<
+  Metadata extends SchemaMetadataStructure,
+  TableName extends keyof Metadata['relationships'] & string,
+  FieldName extends keyof Metadata['relationships'][TableName] & string,
+> = Metadata['relationships'][TableName][FieldName]['table'];
+
+// ============================================================================
+// ACCESS SCHEMA HELPERS
+// ============================================================================
+
+export interface AccessDefinition {
+  readonly signIn: {
+    readonly params: Record<string, ColumnSchema>;
+  };
+  readonly signup: {
+    readonly params: Record<string, ColumnSchema>;
+  };
+}
+
+// ============================================================================
+// ARRAY-BASED SCHEMA TYPE HELPERS
+// ============================================================================
+
+/**
+ * Base schema structure for array-based schemas
+ */
+export interface SchemaStructure {
+  readonly tables: readonly {
+    readonly name: string;
+    readonly columns: Record<string, ColumnSchema>;
+    readonly primaryKey: readonly string[];
+  }[];
+  readonly relationships: readonly {
+    readonly from: string;
+    readonly field: string;
+    readonly to: string;
+    readonly cardinality: Cardinality;
+  }[];
+  readonly backends: Record<string, HTTPOutboxBackendDefinition>;
+  readonly access?: Record<string, AccessDefinition>;
+}
+
+export interface HTTPOutboxBackendDefinition {
+  readonly outboxTable: string;
+  readonly routes: Record<string, HTTPBackendRouteDefinition>;
+}
+
+export interface HTTPBackendRouteDefinition {
+  readonly args: Record<string, HTTPBackendRouteArgsDefinition>;
+}
+
+export interface HTTPBackendRouteArgsDefinition {
+  readonly type: ValueType;
+  readonly optional: boolean;
+}
+
+// ============================================================================
+// BACKEND / RUN TYPE HELPERS
+// ============================================================================
+
+/** Extract all backend names from the schema */
+export type BackendNames<S extends SchemaStructure> = keyof S['backends'] & string;
+
+/** Extract all route paths for a specific backend */
+export type BackendRoutes<
+  S extends SchemaStructure,
+  B extends BackendNames<S>,
+> = keyof S['backends'][B]['routes'] & string;
+
+/** Build the typed payload for a specific route */
+export type RoutePayload<
+  S extends SchemaStructure,
+  B extends BackendNames<S>,
+  R extends BackendRoutes<S, B>,
+> = [keyof RouteArgsDef<S, B, R>] extends [never]
+  ? Record<string, never>
+  : Prettify<
+      { [K in RequiredRouteArgKeys<S, B, R>]: TypeNameToTypeMap[RouteArgsDef<S, B, R>[K]['type']] }
+      &
+      { [K in OptionalRouteArgKeys<S, B, R>]?: TypeNameToTypeMap[RouteArgsDef<S, B, R>[K]['type']] }
+    >;
+
+type RouteArgsDef<
+  S extends SchemaStructure,
+  B extends BackendNames<S>,
+  R extends BackendRoutes<S, B>,
+> = S['backends'][B]['routes'][R]['args'];
+
+type RequiredRouteArgKeys<
+  S extends SchemaStructure,
+  B extends BackendNames<S>,
+  R extends BackendRoutes<S, B>,
+> = {
+  [K in keyof RouteArgsDef<S, B, R>]: RouteArgsDef<S, B, R>[K]['optional'] extends true ? never : K;
+}[keyof RouteArgsDef<S, B, R>] & string;
+
+type OptionalRouteArgKeys<
+  S extends SchemaStructure,
+  B extends BackendNames<S>,
+  R extends BackendRoutes<S, B>,
+> = {
+  [K in keyof RouteArgsDef<S, B, R>]: RouteArgsDef<S, B, R>[K]['optional'] extends true ? K : never;
+}[keyof RouteArgsDef<S, B, R>] & string;
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * Extract a specific table by name from the schema tables array
+ */
+export type GetTable<S extends SchemaStructure, Name extends TableNames<S>> = Extract<
+  S['tables'][number],
+  { name: Name }
+>;
+
+/**
+ * Extract all table names from the schema
+ */
+export type TableNames<S extends SchemaStructure> = S['tables'][number]['name'];
+
+/**
+ * Extract all field names from a type
+ */
+export type TableFieldNames<T extends { columns: Record<string, ColumnSchema> }> =
+  keyof T['columns'] & string;
+
+/**
+ * Convert table schema columns to a TypeScript model type
+ */
+export type TableModel<T extends { columns: Record<string, ColumnSchema> }> = {
+  [K in keyof T['columns']]: ColumnToTSType<T['columns'][K]>;
+};
+
+/**
+ * Extract all relationships for a specific table from relationships array
+ */
+export type TableRelationships<S extends SchemaStructure, TableName extends string> = Extract<
+  S['relationships'][number],
+  { from: TableName }
+>;
+
+/**
+ * Get relationship field names for a table
+ */
+export type RelationshipFields<
+  S extends SchemaStructure,
+  TableName extends string,
+> = TableRelationships<S, TableName>['field'];
+
+/**
+ * Get specific relationship by table and field
+ */
+export type GetRelationship<
+  S extends SchemaStructure,
+  TableName extends string,
+  Field extends string,
+> = Extract<Extract<S['relationships'][number], { from: TableName }>, { field: Field }>;
+
+/**
+ * Convert array-based schema to indexed format (for internal compatibility)
+ */
+export type SchemaToIndexed<S extends SchemaStructure> = {
+  tables: {
+    [K in S['tables'][number]['name']]: Extract<S['tables'][number], { name: K }>;
+  };
+  relationships: {
+    [K in S['tables'][number]['name']]: {
+      [R in Extract<S['relationships'][number], { from: K }>['field']]: Extract<
+        Extract<S['relationships'][number], { from: K }>,
+        { field: R }
+      >;
+    };
+  };
+};

package/src/types.ts

@@ -0,0 +1,216 @@
+// Import new schema types
+export type {
+  ValueType,
+  ColumnSchema,
+  TableSchemaMetadata,
+  Cardinality,
+  RelationshipMetadata,
+  SchemaMetadataStructure,
+  AccessDefinition,
+} from './table-schema';
+
+// Model types (backward compatibility)
+export type GenericModel = Record<string, any>;
+export type GenericSchema = Record<string, GenericModel>;
+
+/**
+ * Helper to constrain related field names based on relationships metadata
+ */
+export type RelatedField<T extends string, R> = GetRelationshipFields<T, R> & string;
+
+// Query interfaces
+export interface QueryInfo {
+  query: string;
+  hash: number;
+  vars?: Record<string, unknown>;
+}
+
+export interface RelatedQuery {
+  /** The name of the related table to query */
+  relatedTable: string;
+  /** The alias for this subquery result (defaults to relatedTable name) */
+  alias?: string;
+  /** Optional query modifier for the subquery */
+  modifier?: SchemaAwareQueryModifier<SchemaStructure, string>;
+  /** The cardinality of the relationship */
+  cardinality: 'one' | 'many';
+}
+
+export interface QueryOptions<TModel extends GenericModel, IsOne extends boolean> {
+  select?: ((keyof TModel & string) | '*')[];
+  where?: Partial<TModel>;
+  limit?: number;
+  offset?: number;
+  orderBy?: Partial<Record<keyof TModel, 'asc' | 'desc'>>;
+  /** Related tables to include via subqueries */
+  related?: RelatedQuery[];
+  isOne?: IsOne;
+}
+
+export interface LiveQueryOptions<TModel extends GenericModel> extends Omit<
+  QueryOptions<TModel, boolean>,
+  'orderBy'
+> {}
+
+// Import schema types for schema-aware modifiers
+import type {
+  SchemaStructure,
+  TableNames,
+  GetTable,
+  TableModel,
+  TableRelationships,
+  GetRelationship,
+} from './table-schema';
+
+// Query modifier type for related queries - now schema-aware!
+export type QueryModifier<TModel extends GenericModel> = (
+  builder: QueryModifierBuilder<TModel>
+) => QueryModifierBuilder<TModel>;
+
+// Schema-aware query modifier that knows about relationships
+export type SchemaAwareQueryModifier<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  RelatedFields extends Record<string, any> = {},
+> = (
+  builder: SchemaAwareQueryModifierBuilder<S, TableName, {}>
+) => SchemaAwareQueryModifierBuilder<S, TableName, RelatedFields>;
+
+// Simplified query builder interface for modifying subqueries
+export interface QueryModifierBuilder<TModel extends GenericModel> {
+  where(conditions: Partial<TModel>): this;
+  select(...fields: ((keyof TModel & string) | '*')[]): this;
+  limit(count: number): this;
+  offset(count: number): this;
+  orderBy(field: keyof TModel & string, direction?: 'asc' | 'desc'): this;
+  related<Field extends string>(relatedField: Field, modifier?: QueryModifier<any>): this;
+  _getOptions(): QueryOptions<TModel, boolean>;
+}
+
+// Schema-aware query builder interface that understands relationships
+export interface SchemaAwareQueryModifierBuilder<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  RelatedFields extends Record<string, any> = {},
+> {
+  where(conditions: Partial<TableModel<GetTable<S, TableName>>>): this;
+  select(...fields: ((keyof TableModel<GetTable<S, TableName>> & string) | '*')[]): this;
+  limit(count: number): this;
+  offset(count: number): this;
+  orderBy(
+    field: keyof TableModel<GetTable<S, TableName>> & string,
+    direction?: 'asc' | 'desc'
+  ): this;
+  related<
+    Field extends TableRelationships<S, TableName>['field'],
+    Rel extends GetRelationship<S, TableName, Field>,
+    RelatedFields2 extends Record<string, any> = {},
+  >(
+    relatedField: Field,
+    modifier?: SchemaAwareQueryModifier<S, Rel['to'], RelatedFields2>
+  ): SchemaAwareQueryModifierBuilder<
+    S,
+    TableName,
+    RelatedFields & {
+      [K in Field]: {
+        to: Rel['to'];
+        cardinality: Rel['cardinality'];
+        relatedFields: RelatedFields2;
+      };
+    }
+  >;
+  _getOptions(): QueryOptions<TableModel<GetTable<S, TableName>>, boolean>;
+}
+
+/**
+ * Extract fields from a model that are relationship fields (string or string[])
+ * Excludes common non-relationship fields like id, created_at, updated_at, etc.
+ */
+export type RelationshipFields<TModel extends GenericModel> = {
+  [K in keyof TModel]: K extends 'id' | 'created_at' | 'updated_at' | 'deleted_at'
+    ? never
+    : TModel[K] extends string | string[] | null | undefined
+      ? K
+      : never;
+}[keyof TModel];
+
+/**
+ * Helper type to infer the related model type from a field name using Relationships metadata
+ * Simplified to directly access the nested structure
+ */
+export type InferRelatedModelFromMetadata<
+  Schema extends GenericSchema,
+  TableName extends string,
+  FieldName extends string,
+  Relationships,
+> =
+  Relationships extends Record<string, Record<string, RelationshipDefinition>>
+    ? TableName extends keyof Relationships
+      ? FieldName extends keyof Relationships[TableName]
+        ? Relationships[TableName][FieldName]['model']
+        : any
+      : any
+    : any;
+
+/**
+ * Get cardinality for a relationship field from metadata
+ * Simplified to directly access the nested structure
+ */
+export type GetCardinality<TableName extends string, FieldName extends string, Relationships> =
+  Relationships extends Record<string, Record<string, RelationshipDefinition>>
+    ? TableName extends keyof Relationships
+      ? FieldName extends keyof Relationships[TableName]
+        ? Relationships[TableName][FieldName]['cardinality']
+        : 'many'
+      : 'many'
+    : 'many';
+
+/**
+ * Type that transforms a Model by replacing a field with its related records
+ * Uses Relationships metadata to determine cardinality and related table
+ */
+export type WithRelated<
+  Schema extends GenericSchema,
+  TModel extends Record<string, any>,
+  TableName extends string,
+  FieldName extends string,
+  Relationships,
+> = FieldName extends keyof TModel
+  ? Omit<TModel, FieldName> & {
+      [K in FieldName]: GetCardinality<TableName, FieldName, Relationships> extends 'one'
+        ? InferRelatedModelFromMetadata<Schema, TableName, K, Relationships> | null
+        : InferRelatedModelFromMetadata<Schema, TableName, K, Relationships>[] | null;
+    }
+  : TModel;
+
+/**
+ * Type to extract relationship fields from Relationships metadata
+ * Now simplified to just get the keys of the nested object
+ */
+export type GetRelationshipFields<TableName extends string, Relationships> =
+  Relationships extends Record<string, Record<string, any>>
+    ? TableName extends keyof Relationships
+      ? keyof Relationships[TableName] & string
+      : never
+    : never;
+
+/**
+ * Relationship metadata structure - now a nested object for better type safety
+ * Example:
+ * {
+ *   thread: {
+ *     author: { model: Schema["user"], table: "user", cardinality: "one" },
+ *     comments: { model: Schema["comment"], table: "comment", cardinality: "many" }
+ *   }
+ * }
+ */
+export interface RelationshipDefinition<Model = any> {
+  /** The related model type */
+  model: Model;
+  /** The related table name */
+  table: string;
+  /** Whether this is a 1:1 or 1:many relationship */
+  cardinality: 'one' | 'many';
+}
+
+export type RelationshipsMetadata = Record<string, Record<string, RelationshipDefinition>>;

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  external: ['surrealdb'],
+  clean: true,
+  hash: false,
+  sourcemap: true,
+});