@type32/tauri-sqlite-orm 0.2.15 → 0.3.0

package/dist/index.d.mts

@@ -56,8 +56,28 @@ type RelationType = 'one' | 'many';
 interface RelationConfig {
     type: RelationType;
     foreignTable: AnyTable;
+    /** For one: local FK columns. For many (v2): foreign table's FK columns. */
     fields?: AnySQLiteColumn[];
+    /** For one: foreign PK columns. For many (v2): parent table's PK columns. */
     references?: AnySQLiteColumn[];
+    /** For many-to-many via through(): junction table between parent and foreign */
+    junctionTable?: AnyTable;
+    /** Parent column -> junction column (parent PK = junction FK to parent) */
+    fromJunction?: {
+        column: AnySQLiteColumn;
+        junctionColumn: AnySQLiteColumn;
+    };
+    /** Junction column -> foreign column (junction FK to foreign = foreign PK) */
+    toJunction?: {
+        junctionColumn: AnySQLiteColumn;
+        column: AnySQLiteColumn;
+    };
+    /** When false, one relation is required (type-level: T not T | null) */
+    optional?: boolean;
+    /** Alias for the relation (e.g. for self-referential disambiguation) */
+    alias?: string;
+    /** Predefined filter for many relations: (alias) => Condition. Receives the joined table alias. */
+    where?: (alias: string) => unknown;
 }
 
 type Condition = Expression<SqlBool>;
@@ -233,6 +253,8 @@ type RelationsBuilder = {
     one: <U extends AnyTable>(table: U, config?: {
         fields: AnySQLiteColumn[];
         references: AnySQLiteColumn[];
+        optional?: boolean;
+        alias?: string;
     }) => OneRelation<U>;
     many: <U extends AnyTable>(table: U) => ManyRelation<U>;
 };
@@ -361,14 +383,53 @@ declare class OneRelation<T extends AnyTable = AnyTable> extends Relation<T> {
     config?: {
         fields: AnySQLiteColumn[];
         references: AnySQLiteColumn[];
+        optional?: boolean;
+        alias?: string;
     } | undefined;
     constructor(foreignTable: T, config?: {
         fields: AnySQLiteColumn[];
         references: AnySQLiteColumn[];
+        optional?: boolean;
+        alias?: string;
     } | undefined);
 }
 declare class ManyRelation<T extends AnyTable = AnyTable> extends Relation<T> {
-    constructor(foreignTable: T);
+    config?: {
+        from?: AnySQLiteColumn[];
+        to?: AnySQLiteColumn[];
+        through?: {
+            junctionTable: AnyTable;
+            fromRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+            toRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+        };
+        optional?: boolean;
+        alias?: string;
+        where?: (alias: string) => unknown;
+    } | undefined;
+    constructor(foreignTable: T, config?: {
+        from?: AnySQLiteColumn[];
+        to?: AnySQLiteColumn[];
+        through?: {
+            junctionTable: AnyTable;
+            fromRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+            toRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+        };
+        optional?: boolean;
+        alias?: string;
+        where?: (alias: string) => unknown;
+    } | undefined);
 }
 declare const relations: <T extends AnyTable, R extends Record<string, Relation>>(table: T, relationsCallback: (helpers: RelationsBuilder) => R) => R;
 declare const getTableColumns: <T extends AnyTable>(table: T) => Record<string, AnySQLiteColumn>;
@@ -411,9 +472,18 @@ declare const enumType: <TName extends string, TValues extends readonly [string,
 
 /** Maps relations() return type to typed relation configs with foreign table preserved */
 type InferRelationsMap<R extends Record<string, OneRelation | ManyRelation>> = {
-    [K in keyof R]: R[K] extends OneRelation<infer T> ? {
+    [K in keyof R]: R[K] extends OneRelation<infer T> ? R[K] extends {
+        config?: {
+            optional?: infer O;
+        };
+    } ? {
+        type: 'one';
+        foreignTable: T;
+        optional: O;
+    } : {
         type: 'one';
         foreignTable: T;
+        optional?: true;
     } : R[K] extends ManyRelation<infer T> ? {
         type: 'many';
         foreignTable: T;
@@ -440,7 +510,8 @@ type InferRelationFields<TTable extends AnyTable, TRelationsMap extends Record<s
     [K in keyof TWith & keyof TRelationsMap]: TWith[K] extends false | undefined ? never : TRelationsMap[K] extends {
         type: 'one';
         foreignTable: infer T;
-    } ? T extends AnyTable ? InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations> : never : TRelationsMap[K] extends {
+        optional?: infer O;
+    } ? T extends AnyTable ? ([O] extends [false] ? InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations> : (InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations>) | null) : never : TRelationsMap[K] extends {
         type: 'many';
         foreignTable: infer T;
     } ? T extends AnyTable ? (InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations>)[] : never : never;
@@ -484,6 +555,76 @@ type InferRelationalSelectModel<TTable extends AnyTable, TRelations extends Reco
     [K in TTable['_']['name']]: TRelations;
 }> = InferSelectModel<TTable> & InferRelationFields<TTable, InferRelationsMap<TRelations>, TAllRelations, TWith>;
 
+/**
+ * Relations v2 API - Drizzle-style defineRelations with from/to and many-without-one.
+ * Use defineRelations() for a single place to define all relations, or defineRelationsPart() to split into parts.
+ */
+
+/** Options for one() relation - from/to replace fields/references */
+interface OneRelationOptions {
+    from: AnySQLiteColumn | AnySQLiteColumn[];
+    to: AnySQLiteColumn | AnySQLiteColumn[];
+    optional?: boolean;
+    alias?: string;
+}
+/** Reference for through() - column with junction column for many-to-many */
+interface ThroughRef {
+    column: AnySQLiteColumn;
+    junctionColumn: AnySQLiteColumn;
+    junctionTable: AnyTable;
+}
+/** Create a through reference for many-to-many: through(column, junctionColumn, junctionTable) */
+declare function through(column: AnySQLiteColumn, junctionColumn: AnySQLiteColumn, junctionTable: AnyTable): ThroughRef;
+/** Options for many() relation - optional explicit from/to for many-without-one, or through() for many-to-many */
+interface ManyRelationOptions {
+    from?: AnySQLiteColumn | AnySQLiteColumn[] | ThroughRef;
+    to?: AnySQLiteColumn | AnySQLiteColumn[] | ThroughRef;
+    optional?: boolean;
+    alias?: string;
+    /** Predefined filter: (alias) => Condition. Applied to the joined relation table. */
+    where?: (alias: string) => Condition;
+}
+/** Build the r object passed to defineRelations callback */
+declare function buildR<Tables extends Record<string, AnyTable>>(tables: Tables): {
+    [K in keyof Tables]: Record<string, AnySQLiteColumn>;
+} & {
+    one: {
+        [K in keyof Tables]: (opts: OneRelationOptions) => OneRelation<Tables[K]>;
+    };
+    many: {
+        [K in keyof Tables]: (opts?: ManyRelationOptions) => ManyRelation<Tables[K]>;
+    };
+};
+type DefineRelationsCallback<Tables extends Record<string, AnyTable>> = (r: ReturnType<typeof buildR>) => {
+    [K in keyof Tables]?: Record<string, OneRelation | ManyRelation>;
+};
+/**
+ * Define all relations for your schema in one place (v2 API).
+ * Uses from/to instead of fields/references, and supports many-without-one.
+ *
+ * @example
+ * ```ts
+ * import * as schema from './schema'
+ * import { defineRelations } from '@type32/tauri-sqlite-orm'
+ *
+ * export const relations = defineRelations(schema, (r) => ({
+ *   users: {
+ *     posts: r.many.posts({ from: r.users.id, to: r.posts.userId }),
+ *   },
+ *   posts: {
+ *     user: r.one.users({ from: r.posts.userId, to: r.users.id }),
+ *     postTags: r.many.postTags({ from: r.posts.id, to: r.postTags.postId }),
+ *   },
+ * }))
+ * ```
+ */
+declare function defineRelations<TSchema extends Record<string, unknown>>(schema: TSchema, callback: DefineRelationsCallback<Record<string, AnyTable>>): Record<string, Record<string, OneRelation | ManyRelation>>;
+/**
+ * Define a part of relations - merge multiple parts when passing to TauriORM.
+ * Useful for splitting large schema definitions.
+ */
+declare function defineRelationsPart<TSchema extends Record<string, unknown>>(schema: TSchema, callback: DefineRelationsCallback<Record<string, AnyTable>>): Record<string, Record<string, OneRelation | ManyRelation>>;
+
 declare class TauriORMError extends Error {
     constructor(message: string);
 }
@@ -515,4 +656,4 @@ declare class TableNotFoundError extends TauriORMError {
     constructor(tableName: string);
 }
 
-export { type AnySQLiteColumn, type AnyTable, type ColumnDataType, ColumnNotFoundError, type ColumnOptions, type ColumnValueTypes, type Condition, type DatabaseLike, DeleteQueryBuilder, type ExtractColumnType, type InferInsertModel, type InferRelationalSelectModel, type InferRelationsMap, type InferSelectModel, InsertQueryBuilder, InsertValidationError, ManyRelation, MigrationError, MissingWhereClauseError, type Mode, OneRelation, QueryBuilderError, Relation, type RelationConfig, RelationError, type RelationType, type RelationsBuilder, type SQLAggregate, type SQLCondition, type SQLSubquery, SQLiteColumn, SelectQueryBuilder, Table, TableNotFoundError, TauriDialect, TauriORM, TauriORMError, UpdateQueryBuilder, UpdateValidationError, ValidationError, WithQueryBuilder, alias, and, as, asc, avg, between, blob, boolean, contains, count, countDistinct, desc, endsWith, enumType, eq, eqSubquery, exists, getTableColumns, groupConcat, gt, gtSubquery, gte, gteSubquery, ilike, inArray, integer, isNotNull, isNull, like, lt, ltSubquery, lte, lteSubquery, max, min, ne, neSubquery, not, notExists, notIn, numeric, or, real, relations, scalarSubquery, sqliteTable, startsWith, subquery, sum, text };
+export { type AnySQLiteColumn, type AnyTable, type ColumnDataType, ColumnNotFoundError, type ColumnOptions, type ColumnValueTypes, type Condition, type DatabaseLike, type DefineRelationsCallback, DeleteQueryBuilder, type ExtractColumnType, type InferInsertModel, type InferRelationalSelectModel, type InferRelationsMap, type InferSelectModel, InsertQueryBuilder, InsertValidationError, ManyRelation, type ManyRelationOptions, MigrationError, MissingWhereClauseError, type Mode, OneRelation, type OneRelationOptions, QueryBuilderError, Relation, type RelationConfig, RelationError, type RelationType, type RelationsBuilder, type SQLAggregate, type SQLCondition, type SQLSubquery, SQLiteColumn, SelectQueryBuilder, Table, TableNotFoundError, TauriDialect, TauriORM, TauriORMError, type ThroughRef, UpdateQueryBuilder, UpdateValidationError, ValidationError, WithQueryBuilder, alias, and, as, asc, avg, between, blob, boolean, contains, count, countDistinct, defineRelations, defineRelationsPart, desc, endsWith, enumType, eq, eqSubquery, exists, getTableColumns, groupConcat, gt, gtSubquery, gte, gteSubquery, ilike, inArray, integer, isNotNull, isNull, like, lt, ltSubquery, lte, lteSubquery, max, min, ne, neSubquery, not, notExists, notIn, numeric, or, real, relations, scalarSubquery, sqliteTable, startsWith, subquery, sum, text, through };

package/dist/index.d.ts

@@ -56,8 +56,28 @@ type RelationType = 'one' | 'many';
 interface RelationConfig {
     type: RelationType;
     foreignTable: AnyTable;
+    /** For one: local FK columns. For many (v2): foreign table's FK columns. */
     fields?: AnySQLiteColumn[];
+    /** For one: foreign PK columns. For many (v2): parent table's PK columns. */
     references?: AnySQLiteColumn[];
+    /** For many-to-many via through(): junction table between parent and foreign */
+    junctionTable?: AnyTable;
+    /** Parent column -> junction column (parent PK = junction FK to parent) */
+    fromJunction?: {
+        column: AnySQLiteColumn;
+        junctionColumn: AnySQLiteColumn;
+    };
+    /** Junction column -> foreign column (junction FK to foreign = foreign PK) */
+    toJunction?: {
+        junctionColumn: AnySQLiteColumn;
+        column: AnySQLiteColumn;
+    };
+    /** When false, one relation is required (type-level: T not T | null) */
+    optional?: boolean;
+    /** Alias for the relation (e.g. for self-referential disambiguation) */
+    alias?: string;
+    /** Predefined filter for many relations: (alias) => Condition. Receives the joined table alias. */
+    where?: (alias: string) => unknown;
 }
 
 type Condition = Expression<SqlBool>;
@@ -233,6 +253,8 @@ type RelationsBuilder = {
     one: <U extends AnyTable>(table: U, config?: {
         fields: AnySQLiteColumn[];
         references: AnySQLiteColumn[];
+        optional?: boolean;
+        alias?: string;
     }) => OneRelation<U>;
     many: <U extends AnyTable>(table: U) => ManyRelation<U>;
 };
@@ -361,14 +383,53 @@ declare class OneRelation<T extends AnyTable = AnyTable> extends Relation<T> {
     config?: {
         fields: AnySQLiteColumn[];
         references: AnySQLiteColumn[];
+        optional?: boolean;
+        alias?: string;
     } | undefined;
     constructor(foreignTable: T, config?: {
         fields: AnySQLiteColumn[];
         references: AnySQLiteColumn[];
+        optional?: boolean;
+        alias?: string;
     } | undefined);
 }
 declare class ManyRelation<T extends AnyTable = AnyTable> extends Relation<T> {
-    constructor(foreignTable: T);
+    config?: {
+        from?: AnySQLiteColumn[];
+        to?: AnySQLiteColumn[];
+        through?: {
+            junctionTable: AnyTable;
+            fromRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+            toRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+        };
+        optional?: boolean;
+        alias?: string;
+        where?: (alias: string) => unknown;
+    } | undefined;
+    constructor(foreignTable: T, config?: {
+        from?: AnySQLiteColumn[];
+        to?: AnySQLiteColumn[];
+        through?: {
+            junctionTable: AnyTable;
+            fromRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+            toRef: {
+                column: AnySQLiteColumn;
+                junctionColumn: AnySQLiteColumn;
+            };
+        };
+        optional?: boolean;
+        alias?: string;
+        where?: (alias: string) => unknown;
+    } | undefined);
 }
 declare const relations: <T extends AnyTable, R extends Record<string, Relation>>(table: T, relationsCallback: (helpers: RelationsBuilder) => R) => R;
 declare const getTableColumns: <T extends AnyTable>(table: T) => Record<string, AnySQLiteColumn>;
@@ -411,9 +472,18 @@ declare const enumType: <TName extends string, TValues extends readonly [string,
 
 /** Maps relations() return type to typed relation configs with foreign table preserved */
 type InferRelationsMap<R extends Record<string, OneRelation | ManyRelation>> = {
-    [K in keyof R]: R[K] extends OneRelation<infer T> ? {
+    [K in keyof R]: R[K] extends OneRelation<infer T> ? R[K] extends {
+        config?: {
+            optional?: infer O;
+        };
+    } ? {
+        type: 'one';
+        foreignTable: T;
+        optional: O;
+    } : {
         type: 'one';
         foreignTable: T;
+        optional?: true;
     } : R[K] extends ManyRelation<infer T> ? {
         type: 'many';
         foreignTable: T;
@@ -440,7 +510,8 @@ type InferRelationFields<TTable extends AnyTable, TRelationsMap extends Record<s
     [K in keyof TWith & keyof TRelationsMap]: TWith[K] extends false | undefined ? never : TRelationsMap[K] extends {
         type: 'one';
         foreignTable: infer T;
-    } ? T extends AnyTable ? InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations> : never : TRelationsMap[K] extends {
+        optional?: infer O;
+    } ? T extends AnyTable ? ([O] extends [false] ? InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations> : (InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations>) | null) : never : TRelationsMap[K] extends {
         type: 'many';
         foreignTable: infer T;
     } ? T extends AnyTable ? (InferSelectModel<T> & InferNestedFields<T, TWith[K], TAllRelations>)[] : never : never;
@@ -484,6 +555,76 @@ type InferRelationalSelectModel<TTable extends AnyTable, TRelations extends Reco
     [K in TTable['_']['name']]: TRelations;
 }> = InferSelectModel<TTable> & InferRelationFields<TTable, InferRelationsMap<TRelations>, TAllRelations, TWith>;
 
+/**
+ * Relations v2 API - Drizzle-style defineRelations with from/to and many-without-one.
+ * Use defineRelations() for a single place to define all relations, or defineRelationsPart() to split into parts.
+ */
+
+/** Options for one() relation - from/to replace fields/references */
+interface OneRelationOptions {
+    from: AnySQLiteColumn | AnySQLiteColumn[];
+    to: AnySQLiteColumn | AnySQLiteColumn[];
+    optional?: boolean;
+    alias?: string;
+}
+/** Reference for through() - column with junction column for many-to-many */
+interface ThroughRef {
+    column: AnySQLiteColumn;
+    junctionColumn: AnySQLiteColumn;
+    junctionTable: AnyTable;
+}
+/** Create a through reference for many-to-many: through(column, junctionColumn, junctionTable) */
+declare function through(column: AnySQLiteColumn, junctionColumn: AnySQLiteColumn, junctionTable: AnyTable): ThroughRef;
+/** Options for many() relation - optional explicit from/to for many-without-one, or through() for many-to-many */
+interface ManyRelationOptions {
+    from?: AnySQLiteColumn | AnySQLiteColumn[] | ThroughRef;
+    to?: AnySQLiteColumn | AnySQLiteColumn[] | ThroughRef;
+    optional?: boolean;
+    alias?: string;
+    /** Predefined filter: (alias) => Condition. Applied to the joined relation table. */
+    where?: (alias: string) => Condition;
+}
+/** Build the r object passed to defineRelations callback */
+declare function buildR<Tables extends Record<string, AnyTable>>(tables: Tables): {
+    [K in keyof Tables]: Record<string, AnySQLiteColumn>;
+} & {
+    one: {
+        [K in keyof Tables]: (opts: OneRelationOptions) => OneRelation<Tables[K]>;
+    };
+    many: {
+        [K in keyof Tables]: (opts?: ManyRelationOptions) => ManyRelation<Tables[K]>;
+    };
+};
+type DefineRelationsCallback<Tables extends Record<string, AnyTable>> = (r: ReturnType<typeof buildR>) => {
+    [K in keyof Tables]?: Record<string, OneRelation | ManyRelation>;
+};
+/**
+ * Define all relations for your schema in one place (v2 API).
+ * Uses from/to instead of fields/references, and supports many-without-one.
+ *
+ * @example
+ * ```ts
+ * import * as schema from './schema'
+ * import { defineRelations } from '@type32/tauri-sqlite-orm'
+ *
+ * export const relations = defineRelations(schema, (r) => ({
+ *   users: {
+ *     posts: r.many.posts({ from: r.users.id, to: r.posts.userId }),
+ *   },
+ *   posts: {
+ *     user: r.one.users({ from: r.posts.userId, to: r.users.id }),
+ *     postTags: r.many.postTags({ from: r.posts.id, to: r.postTags.postId }),
+ *   },
+ * }))
+ * ```
+ */
+declare function defineRelations<TSchema extends Record<string, unknown>>(schema: TSchema, callback: DefineRelationsCallback<Record<string, AnyTable>>): Record<string, Record<string, OneRelation | ManyRelation>>;
+/**
+ * Define a part of relations - merge multiple parts when passing to TauriORM.
+ * Useful for splitting large schema definitions.
+ */
+declare function defineRelationsPart<TSchema extends Record<string, unknown>>(schema: TSchema, callback: DefineRelationsCallback<Record<string, AnyTable>>): Record<string, Record<string, OneRelation | ManyRelation>>;
+
 declare class TauriORMError extends Error {
     constructor(message: string);
 }
@@ -515,4 +656,4 @@ declare class TableNotFoundError extends TauriORMError {
     constructor(tableName: string);
 }
 
-export { type AnySQLiteColumn, type AnyTable, type ColumnDataType, ColumnNotFoundError, type ColumnOptions, type ColumnValueTypes, type Condition, type DatabaseLike, DeleteQueryBuilder, type ExtractColumnType, type InferInsertModel, type InferRelationalSelectModel, type InferRelationsMap, type InferSelectModel, InsertQueryBuilder, InsertValidationError, ManyRelation, MigrationError, MissingWhereClauseError, type Mode, OneRelation, QueryBuilderError, Relation, type RelationConfig, RelationError, type RelationType, type RelationsBuilder, type SQLAggregate, type SQLCondition, type SQLSubquery, SQLiteColumn, SelectQueryBuilder, Table, TableNotFoundError, TauriDialect, TauriORM, TauriORMError, UpdateQueryBuilder, UpdateValidationError, ValidationError, WithQueryBuilder, alias, and, as, asc, avg, between, blob, boolean, contains, count, countDistinct, desc, endsWith, enumType, eq, eqSubquery, exists, getTableColumns, groupConcat, gt, gtSubquery, gte, gteSubquery, ilike, inArray, integer, isNotNull, isNull, like, lt, ltSubquery, lte, lteSubquery, max, min, ne, neSubquery, not, notExists, notIn, numeric, or, real, relations, scalarSubquery, sqliteTable, startsWith, subquery, sum, text };
+export { type AnySQLiteColumn, type AnyTable, type ColumnDataType, ColumnNotFoundError, type ColumnOptions, type ColumnValueTypes, type Condition, type DatabaseLike, type DefineRelationsCallback, DeleteQueryBuilder, type ExtractColumnType, type InferInsertModel, type InferRelationalSelectModel, type InferRelationsMap, type InferSelectModel, InsertQueryBuilder, InsertValidationError, ManyRelation, type ManyRelationOptions, MigrationError, MissingWhereClauseError, type Mode, OneRelation, type OneRelationOptions, QueryBuilderError, Relation, type RelationConfig, RelationError, type RelationType, type RelationsBuilder, type SQLAggregate, type SQLCondition, type SQLSubquery, SQLiteColumn, SelectQueryBuilder, Table, TableNotFoundError, TauriDialect, TauriORM, TauriORMError, type ThroughRef, UpdateQueryBuilder, UpdateValidationError, ValidationError, WithQueryBuilder, alias, and, as, asc, avg, between, blob, boolean, contains, count, countDistinct, defineRelations, defineRelationsPart, desc, endsWith, enumType, eq, eqSubquery, exists, getTableColumns, groupConcat, gt, gtSubquery, gte, gteSubquery, ilike, inArray, integer, isNotNull, isNull, like, lt, ltSubquery, lte, lteSubquery, max, min, ne, neSubquery, not, notExists, notIn, numeric, or, real, relations, scalarSubquery, sqliteTable, startsWith, subquery, sum, text, through };