pqb 0.18.33 → 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>;

package/dist/index.js

@@ -6185,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');
    *
@@ -7469,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
@@ -8056,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:
@@ -8561,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
@@ -9897,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) {