@expressive/sql 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -45,7 +45,7 @@ declare abstract class Type {
45
45
  static one<T extends Type>(this: Type.EntityType<T>, id: number): Promise<Type.Values<T>>;
46
46
  }
47
47
  declare class Primary extends Field<number> {
48
- readonly type = "int";
48
+ readonly type = "integer";
49
49
  readonly increment = true;
50
50
  readonly optional = true;
51
51
  readonly nullable = false;
@@ -53,8 +53,8 @@ declare class Primary extends Field<number> {
53
53
  readonly unique = true;
54
54
  }
55
55
 
56
- type ANumeric = Query.Value<string | number>;
57
- type Numeric = Query.Value<number>;
56
+ type ANumeric = Query.Match<string | number>;
57
+ type Numeric = Query.Match<number>;
58
58
  interface Bitwise {
59
59
  not(value: Numeric): Numeric;
60
60
  and(left: Numeric, right: Numeric): Numeric;
@@ -75,8 +75,8 @@ interface MathOps {
75
75
  }
76
76
  declare const MathOps: MathOps;
77
77
  declare class Computed<T> extends Value {
78
- readonly left?: Query.Value | Field<T> | Computed<T>;
79
- readonly right: Query.Value | Field<T> | Computed<T>;
78
+ readonly left?: Query.Match | Field<T> | Computed<T>;
79
+ readonly right: Query.Match | Field<T> | Computed<T>;
80
80
  readonly operator: string;
81
81
  readonly rank: number;
82
82
  constructor(operator: string, value: Value | Field<T> | Computed<T>, right?: Value | Field<T> | Computed<T>, rank?: number);
@@ -149,7 +149,7 @@ declare namespace Query {
149
149
  type FromData<T extends {}> = {
150
150
  [K in keyof T]: Field<T[K]>;
151
151
  };
152
- type Value<T = any> = T | Field<T> | Computed<T>;
152
+ type Match<T = any> = T | (T extends Field<infer U> ? Match<U> : Field<T> | Computed<T>);
153
153
  type Insert<T extends Type> = {
154
154
  [K in Type.Required<T>]: Field.Assigns<T[K]> | Field;
155
155
  } & {
@@ -170,7 +170,7 @@ declare namespace Query {
170
170
  *
171
171
  * Will alternate between AND-OR depending on depth, starting with OR.
172
172
  */
173
- (...orWhere: (Cond | Group)[]): Group;
173
+ (...orWhere: Expression[]): Group;
174
174
  /**
175
175
  * Declare inserts to be made into a given table.
176
176
  */
@@ -199,13 +199,19 @@ declare namespace Query {
199
199
  };
200
200
  connection: Connection.Ready;
201
201
  };
202
- type Compare<T extends Field> = ReturnType<T["where"]>;
202
+ type Compare<T> = {
203
+ is(value: Match<T>): Expression;
204
+ not(value: Match<T>): Expression;
205
+ over(value: Match<T>, orEqual?: boolean): Expression;
206
+ under(value: Match<T>, orEqual?: boolean): Expression;
207
+ in(value: Match<T>[]): Expression;
208
+ };
203
209
  type Asserts<T extends Field> = Compare<T> & {
204
210
  asc(): void;
205
211
  desc(): void;
206
212
  };
207
213
  type Updates<T> = Field.Updates<T> | T | Field;
208
- type Function<R> = (this: Builder, where: Where, fn: Query.Functions) => R;
214
+ type Function<R> = (this: Builder, where: Where, fn: Functions) => R;
209
215
  type Factory<R, A extends any[]> = Function<(...args: A) => R>;
210
216
  type Template<A extends any[]> = (...args: A) => Query;
211
217
  type TemplateSelects<T, A extends any[]> = (...args: A) => Selects<T>;
@@ -286,22 +292,29 @@ declare class Builder {
286
292
  commit(returns: unknown): void;
287
293
  inject(args: number): (() => Parameter)[];
288
294
  table(table: Query.From): Query.Verbs<Type>;
295
+ compare<T extends Field>(field: T): {
296
+ is: (right: unknown, orEqual?: boolean) => Expression;
297
+ in: (right: unknown, orEqual?: boolean) => Expression;
298
+ not: (right: unknown, orEqual?: boolean) => Expression;
299
+ over: (right: unknown, orEqual?: boolean) => Expression;
300
+ under: (right: unknown, orEqual?: boolean) => Expression;
301
+ };
289
302
  field<T extends Field>(field: T): {
290
303
  asc: () => void;
291
304
  desc: () => void;
292
- is(value: unknown): Cond;
293
- not(value: unknown): Cond;
294
- over(value: unknown, orEqual?: boolean | undefined): Cond;
295
- under(value: unknown, orEqual?: boolean | undefined): Cond;
296
- in(value: unknown[]): Cond;
305
+ is: (right: unknown, orEqual?: boolean) => Expression;
306
+ in: (right: unknown, orEqual?: boolean) => Expression;
307
+ not: (right: unknown, orEqual?: boolean) => Expression;
308
+ over: (right: unknown, orEqual?: boolean) => Expression;
309
+ under: (right: unknown, orEqual?: boolean) => Expression;
297
310
  };
298
- andOr(...args: (Cond | Group)[]): Group;
311
+ andOr(...args: Expression[]): Group;
299
312
  use<T extends Type>(type: Type.EntityType<T>, optional?: false): Query.From<T>;
300
313
  use<T extends Type>(type: Type.EntityType<T>, optional: boolean): Query.Join<T>;
301
314
  use<T extends Type>(type: Type.EntityType<T>, ...inserts: Type.Insert<T>[]): Query.From<T>;
302
315
  insert<T extends Type>(table: Builder.Table<T>, input: Type.Insert<T>): void;
303
316
  digest(value: any, field: Field): any;
304
- where(left: Field, op: string, right: unknown): Cond | Group;
317
+ where(left: Field, op: string, right: unknown): Expression;
305
318
  with<T extends Record<string, any>>(data: Iterable<T>): { [K in keyof T]: Field<T[K]>; };
306
319
  accept(args: unknown[]): unknown[];
307
320
  parse(raw: Record<string, any>): any;
@@ -338,6 +351,7 @@ declare class DataTable<T extends Record<string, unknown> = any> extends Paramet
338
351
  constructor(parent: Builder, input: Iterable<T>);
339
352
  toParam(): any;
340
353
  }
354
+ type Expression = Cond | Group;
341
355
  declare class Cond {
342
356
  readonly left: Field;
343
357
  readonly op: string;
@@ -346,9 +360,9 @@ declare class Cond {
346
360
  constructor(left: Field, op: string, right: unknown, restricted?: boolean);
347
361
  }
348
362
  declare class Group {
349
- children: Set<Cond | Group>;
350
- add(left: Field | Group | Cond, op?: string, right?: unknown): Cond | Group;
351
- delete(child: Cond | Group): void;
363
+ children: Set<Expression>;
364
+ add(left: Field | Expression, op?: string, right?: unknown): Expression;
365
+ delete(child: Expression): void;
352
366
  get size(): number;
353
367
  }
354
368
  declare class QueryTemplate extends Value {
@@ -365,18 +379,19 @@ type Optional = {
365
379
  };
366
380
  declare namespace Field {
367
381
  type Init<T extends Field = Field> = (self: T) => Partial<T> | void;
368
- type Opts<T extends Field = Field> = Partial<T> | Init<T>;
369
- type Modifier<T, TT extends Field> = T extends {
382
+ type Opts<T extends Field = Field> = Partial<T>;
383
+ type Modifier<T, TT> = T extends {
370
384
  nullable: true;
371
- } ? TT & Nullable : T extends {
385
+ } | true ? TT & Nullable : T extends {
372
386
  fallback?: any;
373
387
  increment?: true;
374
388
  } ? TT & Optional : TT;
375
- type Specify<T, TT extends Field, D extends Field = TT> = Modifier<T, T extends {
389
+ type Type<T, A, D extends Field = any> = T extends {
376
390
  type: infer U;
377
- } ? Extract<TT, {
378
- type: U;
379
- }> : D>;
391
+ } ? (U extends keyof A ? A[U] : D) : A extends {
392
+ default: infer U;
393
+ } ? U : D;
394
+ type Infer<T, A, D extends Field = any> = Modifier<T, Type<T, A, D>>;
380
395
  type Returns<T> = Field & {
381
396
  get(value: any): T;
382
397
  };
@@ -389,33 +404,26 @@ declare namespace Field {
389
404
  type Updates<T> = T extends Accepts<infer U> ? (T extends Nullable ? U | null : U) | undefined : never;
390
405
  type Assigns<T> = T extends Accepts<infer U> ? T extends Nullable ? U | null | undefined : T extends Optional ? U | undefined : U : never;
391
406
  type Output = Record<string, string | number>;
392
- type Compare<T> = {
393
- is(value: Query.Value<T>): Cond;
394
- not(value: Query.Value<T>): Cond;
395
- over(value: Query.Value<T>, orEqual?: boolean): Cond;
396
- under(value: Query.Value<T>, orEqual?: boolean): Cond;
397
- in(value: Query.Value<T>[]): Cond;
398
- };
407
+ const does: (callback: Callback) => void;
399
408
  }
400
409
  declare class Field<T = unknown> {
401
- private options?;
402
410
  type: string;
403
411
  unique: boolean;
404
412
  nullable: boolean;
405
413
  optional: boolean;
406
414
  increment: boolean;
407
415
  fallback?: unknown;
416
+ column: string;
408
417
  property: string;
409
418
  parent: Type.EntityType;
410
419
  table?: Query.Table;
411
420
  query?: Builder;
412
- foreignKey?: string;
413
- foreignTable?: string;
421
+ /** If column has a reference constraint, applicable field is listed here. */
422
+ reference?: Field;
414
423
  /** Real datatype of this field in database. */
415
- datatype: string;
416
- column: string;
417
- constructor(options?: Field.Opts<Field<unknown>> | undefined);
418
- init(property: string, parent: Type.EntityType): this;
424
+ get datatype(): string;
425
+ static new<T extends Field>(this: new (...args: any[]) => T, options?: Field.Opts<T> | boolean): Field;
426
+ create(property: string, parent: Type.EntityType): this;
419
427
  /**
420
428
  * Optional method generates value of property this Field is applied to when accessed inside a query.
421
429
  * If not defined, the value will be the Field itself.
@@ -436,177 +444,219 @@ declare class Field<T = unknown> {
436
444
  * a TINYINT(1) field to a boolean, or a DATETIME field to a Date object.
437
445
  */
438
446
  get(value: any): T;
439
- raw(value: T): string;
440
- /**
441
- * This method is used to compare this field with another value in a query.
442
- *
443
- * @param acc Set of comparisons to be added to if not part of a group.
444
- */
445
- where(): Field.Compare<T>;
446
447
  }
448
+ type Callback = (parent: Type.EntityType, property: string) => void;
447
449
 
448
450
  declare class BooleanColumn extends Field<boolean> {
449
- readonly type: "tinyint" | "varchar";
450
- readonly datatype: string;
451
- readonly TRUE: string | number;
452
- readonly FALSE: string | number;
453
- constructor(opts?: Bool.Opts);
451
+ readonly type: Bool.DataType;
452
+ readonly either?: readonly [true: string, false: string];
454
453
  get(value: unknown): boolean;
455
454
  set(value: boolean): string | number;
456
455
  }
457
456
  declare namespace Bool {
458
- interface TinyInt extends BooleanColumn {
459
- readonly type: "tinyint";
460
- }
461
- interface Char extends BooleanColumn {
462
- readonly type: "varchar";
463
- either?: [true: string, false: string];
457
+ /**
458
+ * Defines all available types of boolean columns.
459
+ * Each type represents a different way to store boolean values.
460
+ * SQL adapters will implement these types and add to interface using type as key.
461
+ * "default" is what should be returned when no type is specified by `Bool({ ... })`.
462
+ *
463
+ * @example
464
+ * declare module "@expressive/sql" {
465
+ * namespace Bool {
466
+ * interface Boolean extends Bool {
467
+ * readonly type: "boolean";
468
+ * }
469
+ *
470
+ * interface Types {
471
+ * default: Boolean;
472
+ * boolean: Boolean;
473
+ * }
474
+ * }
475
+ * }
476
+ */
477
+ interface Types {
464
478
  }
465
- type Any = TinyInt | Char;
479
+ /** All available type identifiers for Bool */
480
+ type DataType = keyof Types;
481
+ /** All available database types for Bool */
482
+ type Any = Types[keyof Types] | BooleanColumn;
466
483
  type Opts = Partial<Any>;
467
484
  }
468
- interface Bool extends BooleanColumn {
469
- }
470
- declare function Bool<T extends Bool.Opts>(opts?: T): Field.Modifier<T, T extends {
471
- type: infer U;
472
- } ? Extract<Bool.TinyInt, {
473
- type: U;
474
- }> | Extract<Bool.Char, {
475
- type: U;
476
- }> : Bool.Any>;
485
+ type Bool = Bool.Any;
486
+ declare function Bool<T extends boolean>(nullable: T): Field.Infer<T, Bool.Types, Bool>;
487
+ declare function Bool<T extends Bool.Opts>(opts?: T): Field.Infer<T, Bool.Types, Bool>;
477
488
  declare namespace Bool {
478
489
  var Type: typeof BooleanColumn;
479
490
  }
480
491
 
481
492
  declare class NumericColumn extends Field<number> {
482
- readonly type: "int" | "tinyint" | "smallint" | "bigint" | "float" | "double";
493
+ readonly type: Num.DataType;
494
+ readonly precision?: number;
495
+ readonly scale?: number;
483
496
  set(value: number): number;
484
497
  }
485
498
  declare namespace Num {
486
- interface Int extends Num {
487
- readonly type: "int";
488
- }
489
- interface TinyInt extends Num {
490
- readonly type: "tinyint";
491
- }
492
- interface SmallInt extends Num {
493
- readonly type: "smallint";
494
- }
495
- interface BigInt extends Num {
496
- readonly type: "bigint";
497
- }
498
- interface Float extends Num {
499
- readonly type: "float";
500
- }
501
- interface Double extends Num {
502
- readonly type: "double";
499
+ /**
500
+ * Defines all available types of numeric columns.
501
+ * Each type represents a different kind of numeric data storage.
502
+ * SQL adapters will implement these types and add to interface using type as key.
503
+ * "default" is what should be returned when no type is specified by `Num({ ... })`.
504
+ *
505
+ * @example
506
+ * declare module "@expressive/sql" {
507
+ * namespace Num {
508
+ * interface Integer extends Num {
509
+ * readonly type: "integer";
510
+ * }
511
+ *
512
+ * interface Decimal extends Num {
513
+ * readonly type: "decimal";
514
+ * readonly precision: number;
515
+ * readonly scale: number;
516
+ * }
517
+ *
518
+ * interface Types {
519
+ * default: Integer;
520
+ * integer: Integer;
521
+ * decimal: Decimal;
522
+ * }
523
+ * }
524
+ * }
525
+ */
526
+ interface Types {
503
527
  }
504
- type Any = Int | TinyInt | SmallInt | BigInt | Float | Double;
528
+ /** All available type identifiers for Num */
529
+ type DataType = keyof Types;
530
+ /** All available database types for Num */
531
+ type Any = Types[keyof Types] | NumericColumn;
505
532
  type Opts = Partial<Any>;
506
533
  }
507
- interface Num extends NumericColumn {
508
- }
509
- declare function Num<T extends Num.Opts>(opts?: T): Field.Modifier<T, T extends {
510
- type: infer U;
511
- } ? Extract<Num.Int, {
512
- type: U;
513
- }> | Extract<Num.TinyInt, {
514
- type: U;
515
- }> | Extract<Num.SmallInt, {
516
- type: U;
517
- }> | Extract<Num.BigInt, {
518
- type: U;
519
- }> | Extract<Num.Float, {
520
- type: U;
521
- }> | Extract<Num.Double, {
522
- type: U;
523
- }> : Num.Int>;
534
+ type Num = Num.Any;
535
+ declare function Num<T extends boolean>(nullable: T): Field.Infer<T, Num.Types, Num>;
536
+ declare function Num<T extends Num.Opts>(opts?: T): Field.Infer<T, Num.Types, Num>;
524
537
  declare namespace Num {
525
538
  var Type: typeof NumericColumn;
526
539
  }
527
540
 
528
- declare class ForeignColumn<T extends Type> extends Field<Type.Values<T>> {
541
+ declare class ForeignColumn<T extends Type = Type> extends Field<Type.Values<T>> {
542
+ readonly type: One.DataType;
529
543
  readonly entity: Type.EntityType<T>;
530
- readonly foreignKey: string;
531
- readonly foreignTable: string;
532
544
  readonly nullable: boolean;
533
- constructor(type: Type.EntityType<T>, nullable?: boolean);
545
+ readonly onDelete?: string;
546
+ readonly onUpdate?: string;
534
547
  set(value: Type.Values<T> | number): any;
535
548
  use(query: Builder): any;
536
549
  }
550
+ declare namespace One {
551
+ interface Types {
552
+ }
553
+ type DataType = keyof Types;
554
+ type Options = {
555
+ [K in Exclude<keyof ForeignColumn, 'entity'>]?: ForeignColumn[K];
556
+ };
557
+ }
537
558
  interface One<T extends Type> extends ForeignColumn<T> {
538
559
  }
539
- declare function One<T extends Type>(type: Type.EntityType<T>, nullable?: false): One<T>;
540
- declare function One<T extends Type>(type: Type.EntityType<T>, nullable: boolean): One<T> & Nullable;
560
+ declare function One<T extends Type>(entity: Type.EntityType<T>, nullable?: false): One<T>;
561
+ declare function One<T extends Type>(entity: Type.EntityType<T>, nullable: boolean): One<T> & Nullable;
562
+ declare function One<T extends Type, O extends One.Options>(entity: Type.EntityType<T>, options: O): Field.Modifier<O, One<T>>;
541
563
  declare namespace One {
542
564
  var Type: typeof ForeignColumn;
543
565
  }
544
566
 
545
567
  declare class StringColumn extends Field<string> {
546
- readonly type: "char" | "varchar" | "text" | "tinytext" | "mediumtext" | "longtext";
547
- readonly length = 255;
548
- constructor(opts?: Str.Opts);
568
+ readonly type: Str.DataType;
569
+ readonly length?: number;
549
570
  set(value: string): string;
550
571
  }
551
572
  declare namespace Str {
552
- interface Char extends Str {
553
- readonly type: "char";
554
- }
555
- interface VarChar extends Str {
556
- readonly type: "varchar";
557
- }
558
- interface Text extends Str {
559
- readonly type: "text";
560
- }
561
- interface TinyText extends Str {
562
- readonly type: "tinytext";
563
- }
564
- interface MediumText extends Str {
565
- readonly type: "mediumtext";
566
- }
567
- interface LongText extends Str {
568
- readonly type: "longtext";
573
+ /**
574
+ * Defines all available types of Str.
575
+ * Each type is a different kind of string column.
576
+ * SQL adapters will implement these types and add to interface using type as key.
577
+ * "default" is what should be returned when no type is specified by `Str({ ... })`.
578
+ *
579
+ * @example
580
+ * declare module "@expressive/sql" {
581
+ * namespace Str {
582
+ * interface Types {
583
+ * default: Str.Text;
584
+ * varchar: Str.VarChar;
585
+ * }
586
+ *
587
+ * interface Text extends Str {
588
+ * readonly type: "text";
589
+ * }
590
+ *
591
+ * interface VarChar extends Str {
592
+ * readonly type: "varchar";
593
+ * readonly length: number;
594
+ * }
595
+ * }
596
+ * }
597
+ */
598
+ interface Types {
569
599
  }
570
- type Any = Char | VarChar | Text | TinyText | MediumText | LongText;
571
- type Opts = Partial<Any>;
572
- }
573
- interface Str extends StringColumn {
574
- }
575
- declare function Str<T extends Str.Opts>(opts?: T): Field.Modifier<T, T extends {
576
- type: infer U;
577
- } ? Extract<Str.Char, {
578
- type: U;
579
- }> | Extract<Str.VarChar, {
580
- type: U;
581
- }> | Extract<Str.Text, {
582
- type: U;
583
- }> | Extract<Str.TinyText, {
584
- type: U;
585
- }> | Extract<Str.MediumText, {
586
- type: U;
587
- }> | Extract<Str.LongText, {
588
- type: U;
589
- }> : Str.VarChar>;
600
+ /** All available types of Str */
601
+ type DataType = keyof Types;
602
+ /** All available database types for Str */
603
+ type Any = Types[keyof Types] | StringColumn;
604
+ type Options = Partial<Any>;
605
+ }
606
+ type Str = Str.Any;
607
+ declare function Str<T extends boolean>(nullable: T): Field.Infer<T, Str.Types, Str>;
608
+ declare function Str<T extends Str.Options>(opts?: T): Field.Infer<T, Str.Types, Str>;
590
609
  declare namespace Str {
591
610
  var Type: typeof StringColumn;
592
611
  }
593
612
 
594
613
  declare class TimeColumn extends Field<Date> {
595
- readonly type: "datetime";
614
+ readonly type: Time.DataType;
596
615
  readonly fallback?: "NOW" | Date;
597
- get(value: string): Date;
598
- set(value: string | Date): string;
599
- }
600
- interface Time extends TimeColumn {
616
+ readonly precision?: number;
617
+ get(value: string | Date): Date;
618
+ set(value: string | Date): string | number;
601
619
  }
602
- declare function Time(options?: Partial<Time>): Time;
620
+ declare namespace Time {
621
+ /**
622
+ * Defines all available types of Time columns.
623
+ * Each type represents a different way to store date/time values.
624
+ * SQL adapters will implement these types and add to interface using type as key.
625
+ * "default" is what should be returned when no type is specified by `Time({ ... })`.
626
+ *
627
+ * @example
628
+ * declare module "@expressive/sql" {
629
+ * namespace Time {
630
+ * interface Timestamp extends Time {
631
+ * readonly type: "timestamp";
632
+ * readonly precision?: number;
633
+ * }
634
+ *
635
+ * interface Types {
636
+ * default: Timestamp;
637
+ * timestamp: Timestamp;
638
+ * }
639
+ * }
640
+ * }
641
+ */
642
+ interface Types {
643
+ }
644
+ /** All available type identifiers for Time */
645
+ type DataType = keyof Types;
646
+ /** All available database types for Time */
647
+ type Any = Types[keyof Types] | TimeColumn;
648
+ type Options = Partial<Any>;
649
+ }
650
+ type Time = Time.Any;
651
+ declare function Time<T extends boolean>(nullable: T): Field.Infer<T, Time.Types, Time>;
652
+ declare function Time<T extends Time.Options>(opts?: T): Field.Infer<T, Time.Types, Time>;
603
653
  declare namespace Time {
604
654
  var Type: typeof TimeColumn;
605
655
  }
606
656
 
607
657
  declare namespace Table {
608
658
  interface Options {
609
- name?: string;
659
+ table?: string;
610
660
  schema?: string;
611
661
  }
612
662
  }