pqb 0.18.32 → 0.18.34

package/dist/index.d.ts

@@ -591,6 +591,73 @@ type DbResult<ColumnTypes> = Db<string, Record<string, never>, EmptyObject, Colu
     adapter: Adapter;
     close: Adapter['close'];
 };
+/**
+ * For the case of using the query builder as a standalone tool, use `createDb` from `pqb` package.
+ *
+ * As `Orchid ORM` focuses on ORM usage, docs examples mostly demonstrates how to work with ORM-defined tables,
+ * but everything that's not related to table relations should also work with `pqb` query builder on its own.
+ *
+ * It is accepting the same options as `orchidORM` + options of `createBaseTable`:
+ *
+ * ```ts
+ * import { createDb } from 'orchid-orm';
+ *
+ * const db = createDb({
+ *   // db connection options
+ *   databaseURL: process.env.DATABASE_URL,
+ *   log: true,
+ *
+ *   // columns in db are in snake case:
+ *   snakeCase: true,
+ *
+ *   // override default SQL for timestamp, see `nowSQL` above
+ *   nowSQL: `now() AT TIME ZONE 'UTC'`,
+ *
+ *   // override column types:
+ *   columnTypes: (t) => ({
+ *     // by default timestamp is returned as a string, override to a number
+ *     timestamp: () => t.timestamp().asNumber(),
+ *   }),
+ * });
+ * ```
+ *
+ * After `db` is defined, construct queryable tables in such way:
+ *
+ * ```ts
+ * export const User = db('user', (t) => ({
+ *   id: t.identity().primaryKey(),
+ *   name: t.text(3, 100),
+ *   password: t.text(8, 200),
+ *   age: t.integer().nullable(),
+ *   ...t.timestamps(),
+ * }));
+ * ```
+ *
+ * Now the `User` can be used for making type-safe queries:
+ *
+ * ```ts
+ * const users = await User.select('id', 'name') // only known columns are allowed
+ *   .where({ age: { gte: 20 } }) // gte is available only on the numeric field, and the only number is allowed
+ *   .order({ createdAt: 'DESC' }) // type safe as well
+ *   .limit(10);
+ *
+ * // users array has a proper type of Array<{ id: number, name: string }>
+ * ```
+ *
+ * The optional third argument is for table options:
+ *
+ * ```ts
+ * const Table = db('table', (t) => ({ ...columns }), {
+ *   // provide this value if the table belongs to a specific database schema:
+ *   schema: 'customTableSchema',
+ *   // override `log` option of `createDb`:
+ *   log: true, // boolean or object described `createdDb` section
+ *   logger: { ... }, // override logger
+ *   noPrimaryKey: 'ignore', // override noPrimaryKey
+ *   snakeCase: true, // override snakeCase
+ * })
+ * ```
+ */
 declare const createDb: <ColumnTypes extends Record<string, orchid_core.AnyColumnTypeCreator> = DefaultColumnTypes>({ log, logger, columnTypes: ctOrFn, snakeCase, nowSQL, ...options }: DbOptions<ColumnTypes>) => DbResult<ColumnTypes>;
 
 type ToSQLCtx = {
@@ -1891,7 +1958,7 @@ declare class QueryGet {
      * It will throw `NotFoundError` when not found.
      *
      * ```ts
-     * import { NumberColumn } from 'pqb';
+     * import { NumberColumn } from 'orchid-orm';
      *
      * const firstName: string = await db.table.get('name');
      *
@@ -3754,7 +3821,7 @@ declare abstract class JsonModifiers extends QueryBase {
      * Selects a value from JSON data using a JSON path.
      *
      * ```ts
-     * import { columnTypes } from 'pqb';
+     * import { columnTypes } from 'orchid-orm';
      *
      * db.table.jsonPathQuery(
      *   columnTypes.text(3, 100), // type of the value
@@ -4001,7 +4068,7 @@ declare class With {
      * Add Common Table Expression (CTE) to the query.
      *
      * ```ts
-     * import { columnTypes } from 'pqb';
+     * import { columnTypes } from 'orchid-orm';
      * import { NumberColumn } from './number';
      *
      * // .with optionally accepts such options:
@@ -4345,7 +4412,7 @@ declare class Update {
      * To make sure that at least one row was updated use `updateOrThrow`:
      *
      * ```ts
-     * import { NotFoundError } from 'pqb';
+     * import { NotFoundError } from 'orchid-orm';
      *
      * try {
      *   // updatedCount is guaranteed to be greater than 0
@@ -5635,6 +5702,20 @@ declare class QueryMethods<ColumnTypes> {
      * await selectFollowing(db.user.select('id', 'name'), currentUser);
      * ```
      *
+     * To get the result type of query helper, use `QueryHelperResult` type:
+     *
+     * ```ts
+     * import { QueryHelperResult } from 'orchid-orm';
+     *
+     * const selectHelper = db.table.makeHelper((q) => q.select('id', 'name'));
+     *
+     * // This type is identical to `db.table.select('id', 'name')`
+     * type SelectQuery = QueryHelperResult<typeof selectHelper>;
+     *
+     * // Await to get result, the type is `{ id: number, name: string }[]`
+     * type Result = Awaited<QueryHelperResult<typeof selectHelper>>;
+     * ```
+     *
      * @param fn - helper function
      */
     makeHelper<T extends Query, Args extends unknown[], Result>(this: T, fn: (q: T, ...args: Args) => Result): QueryHelper<T, Args, Result>;
@@ -5975,7 +6056,6 @@ declare class BigSerialColumn extends NumberAsStringBaseColumn {
     toCode(t: string): Code;
 }
 
-type StringColumn = ColumnType<string, typeof Operators.text>;
 type TextColumnData = StringTypeData;
 type TextMethods = typeof stringTypeMethods;
 interface TextBaseColumn extends ColumnType<string, typeof Operators.text>, TextMethods {
@@ -6007,6 +6087,10 @@ declare class VarCharColumn<Limit extends number | undefined = undefined> extend
     dataType: "varchar";
     toCode(t: string): Code;
 }
+declare class StringColumn<Limit extends number = 255> extends VarCharColumn<Limit> {
+    constructor(limit?: Limit);
+    toCode(t: string): Code;
+}
 declare class CharColumn<Limit extends number | undefined = undefined> extends LimitedTextBaseColumn<Limit> {
     dataType: "char";
     toCode(t: string): Code;
@@ -6645,7 +6729,7 @@ type DefaultColumnTypes = TimestampHelpers & {
     varchar<Limit extends number | undefined = undefined>(limit?: Limit): VarCharColumn<Limit>;
     char<Limit extends number | undefined = undefined>(limit?: Limit): CharColumn<Limit>;
     text(min: number, max: number): TextColumn;
-    string<Limit extends number = 255>(limit?: Limit): VarCharColumn<Limit>;
+    string<Limit extends number = 255>(limit?: Limit): StringColumn<Limit>;
     citext(min: number, max: number): CitextColumn;
     bytea(): ByteaColumn;
     date(): DateColumn;

package/dist/index.js

@@ -2859,6 +2859,21 @@ class VarCharColumn extends LimitedTextBaseColumn {
     );
   }
 }
+class StringColumn extends VarCharColumn {
+  constructor(limit = 255) {
+    super(limit);
+  }
+  toCode(t) {
+    let max = this.data.maxChars;
+    if (max === 255)
+      max = void 0;
+    return columnCode(
+      this,
+      t,
+      `string(${max != null ? max : ""})${orchidCore.stringDataToCode(this.data)}`
+    );
+  }
+}
 class CharColumn extends LimitedTextBaseColumn {
   constructor() {
     super(...arguments);
@@ -3616,7 +3631,7 @@ const columnTypes = __spreadValues$9({
     return new TextColumn(min, max);
   },
   string(limit = 255) {
-    return new VarCharColumn(limit);
+    return new StringColumn(limit);
   },
   citext(min, max) {
     return new CitextColumn(min, max);
@@ -6170,7 +6185,7 @@ class QueryGet {
    * It will throw `NotFoundError` when not found.
    *
    * ```ts
-   * import { NumberColumn } from 'pqb';
+   * import { NumberColumn } from 'orchid-orm';
    *
    * const firstName: string = await db.table.get('name');
    *
@@ -7454,7 +7469,7 @@ class JsonModifiers extends QueryBase {
    * Selects a value from JSON data using a JSON path.
    *
    * ```ts
-   * import { columnTypes } from 'pqb';
+   * import { columnTypes } from 'orchid-orm';
    *
    * db.table.jsonPathQuery(
    *   columnTypes.text(3, 100), // type of the value
@@ -8041,7 +8056,7 @@ class With {
    * Add Common Table Expression (CTE) to the query.
    *
    * ```ts
-   * import { columnTypes } from 'pqb';
+   * import { columnTypes } from 'orchid-orm';
    * import { NumberColumn } from './number';
    *
    * // .with optionally accepts such options:
@@ -8546,7 +8561,7 @@ class Update {
    * To make sure that at least one row was updated use `updateOrThrow`:
    *
    * ```ts
-   * import { NotFoundError } from 'pqb';
+   * import { NotFoundError } from 'orchid-orm';
    *
    * try {
    *   // updatedCount is guaranteed to be greater than 0
@@ -9882,6 +9897,20 @@ class QueryMethods {
    * await selectFollowing(db.user.select('id', 'name'), currentUser);
    * ```
    *
+   * To get the result type of query helper, use `QueryHelperResult` type:
+   *
+   * ```ts
+   * import { QueryHelperResult } from 'orchid-orm';
+   *
+   * const selectHelper = db.table.makeHelper((q) => q.select('id', 'name'));
+   *
+   * // This type is identical to `db.table.select('id', 'name')`
+   * type SelectQuery = QueryHelperResult<typeof selectHelper>;
+   *
+   * // Await to get result, the type is `{ id: number, name: string }[]`
+   * type Result = Awaited<QueryHelperResult<typeof selectHelper>>;
+   * ```
+   *
    * @param fn - helper function
    */
   makeHelper(fn) {
@@ -10426,6 +10455,7 @@ exports.Select = Select;
 exports.SerialColumn = SerialColumn;
 exports.SmallIntColumn = SmallIntColumn;
 exports.SmallSerialColumn = SmallSerialColumn;
+exports.StringColumn = StringColumn;
 exports.TextBaseColumn = TextBaseColumn;
 exports.TextColumn = TextColumn;
 exports.Then = Then;