@juit/pgproxy-model 0.0.0

package/README.md

@@ -0,0 +1,12 @@
+# PostgreSQL Proxy Persister Model Types
+
+This package exports _only the types_ required by the [PGProxy Persister
+interface](https://github.com/juitnow/juit-pgproxy/blob/main/workspaces/persister/README.md).
+
+This simplifies type management allowing **consumers** of libraries and APIs
+using Persister to ship this (and their inferred types) as a simple dependency
+without bringing in any extra code.
+
+* [PGProxy](https://github.com/juitnow/juit-pgproxy/blob/main/README.md)
+* [Copyright Notice](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)
+* [License](https://github.com/juitnow/juit-pgproxy/blob/main/NOTICE.md)

package/dist/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './model';
+export type * from './search';

package/dist/index.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": [],
+  "mappings": "",
+  "names": []
+}

package/dist/model.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// model.ts
+var model_exports = {};
+module.exports = __toCommonJS(model_exports);
+//# sourceMappingURL=model.cjs.map

package/dist/model.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/model.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/dist/model.d.ts

@@ -0,0 +1,34 @@
+import type { OnlyStrings, Prettify } from './utils';
+/** The definition of a column */
+export interface ColumnDefinition<T = any> {
+    /** The TypeScript type of the column (from the type parser) */
+    type: T;
+    /** Whether the column is _generated_ or not */
+    isGenerated?: boolean;
+    /** Whether the column is _nullable_ or not */
+    isNullable?: boolean;
+    /** Whether the column _specifies a default value_ or not */
+    hasDefault?: boolean;
+}
+/** Infer the TypeScript type suitable for an `INSERT` in a table */
+export type InferInsertType<Table extends Record<string, ColumnDefinition>> = Prettify<{
+    [Column in keyof Table as Column extends string ? Table[Column]['isGenerated'] extends true ? never : Table[Column]['isNullable'] extends true ? Column : Table[Column]['hasDefault'] extends true ? Column : never : never]?: Table[Column]['isNullable'] extends true ? Table[Column]['type'] | null : Table[Column]['type'];
+} & {
+    [Column in keyof Table as Column extends string ? Table[Column]['isGenerated'] extends true ? never : Table[Column]['isNullable'] extends true ? never : Table[Column]['hasDefault'] extends true ? never : Column : never]-?: Table[Column]['isNullable'] extends true ? Table[Column]['type'] | null : Table[Column]['type'];
+}>;
+/** Infer the TypeScript type suitable for a `SELECT` from a table */
+export type InferSelectType<Table extends Record<string, ColumnDefinition>> = {
+    [Column in keyof Table as Column extends string ? Column : never]-?: (Table[Column]['isNullable'] extends true ? Table[Column]['type'] | null : Table[Column]['type']) & (Table[Column] extends {
+        branding: infer Brand;
+    } ? Brand : unknown);
+};
+/** Infer the TypeScript type suitable for a `UPDATE` in a table */
+export type InferUpdateType<Table extends Record<string, ColumnDefinition>> = {
+    [Column in keyof Table as Column extends string ? Table[Column]['isGenerated'] extends true ? never : Column : never]?: Table[Column]['isNullable'] extends true ? Table[Column]['type'] | null : Table[Column]['type'];
+};
+/** Infer the TypeScript type used for querying records */
+export type InferQueryType<Table extends Record<string, ColumnDefinition>> = {
+    [Column in keyof Table as Column extends string ? Column : never]?: Table[Column]['isNullable'] extends true ? Table[Column]['type'] | null : Table[Column]['type'];
+};
+/** Infer the available sort values for a table (as required by `ORDER BY`) */
+export type InferSort<Table extends Record<string, ColumnDefinition>> = `${OnlyStrings<keyof Table>}${' ASC' | ' asc' | ' DESC' | ' desc' | ''}`;

package/dist/model.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=model.mjs.map

package/dist/model.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": [],
+  "mappings": "",
+  "names": []
+}

package/dist/search.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// search.ts
+var search_exports = {};
+module.exports = __toCommonJS(search_exports);
+//# sourceMappingURL=search.cjs.map

package/dist/search.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/search.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/dist/search.d.ts

@@ -0,0 +1,131 @@
+import type { ColumnDefinition, InferSelectType } from './model';
+import type { Prettify } from './utils';
+/** Simple type to extract joins with a specified sortcolumn */
+type SortableJoins<Joins> = keyof {
+    [key in keyof Joins as Joins[key] extends {
+        sortColumn: string;
+    } ? key : never]: undefined;
+};
+/**
+ * Definition for a simple (straight) join in a {@link Search}
+ */
+export interface SearchJoin<Schema> {
+    /**
+     * The column in _the search table_ (passed to the constructor of
+     * {@link Search}) referencing the specified `refTable` (defined here).
+     *
+     * ```sql
+     * ... LEFT JOIN "refTable" ON "table"."column" = "refTable"."refColumn"
+     *                                      ^^^^^^
+     * ```
+     */
+    column: string;
+    /**
+     * The name of the table to _left join_.
+     *
+     * ```sql
+     * ... LEFT JOIN "refTable" ON "table"."column" = "refTable"."refColumn"
+     *                ^^^^^^^^                         ^^^^^^^^
+     * ```
+     */
+    refTable: string & keyof Schema;
+    /**
+     * The column in the `refTable` referenced by the _the search table_.
+     *
+     * ```sql
+     * ... LEFT JOIN "refTable" ON "table"."column" = "refTable"."refColumn"
+     *                                                            ^^^^^^^^^
+     * ```
+     */
+    refColumn: string;
+    /**
+     * The column in the referenced table to use as default sort column, when
+     * sorting by this join.
+     */
+    sortColumn?: string;
+}
+/**
+ * Definition for joins in a {@link Search}
+ *
+ * Each key is the name of the join as it will appear in the results, and the
+ * value defines how to perform the join.
+ *
+ * See {@link StraightJoin} and {@link LinkedJoin} for details on the fields.
+ */
+export interface SearchJoins<Schema> {
+    [key: string]: SearchJoin<Schema>;
+}
+/** Internal interface defining operators available to *single values* */
+interface ValueSearchFilter<Schema, Table extends string & keyof Schema> {
+    name: string & keyof Schema[Table];
+    field?: string;
+    op?: '=' | '!=' | '>' | '>=' | '<' | '<=' | '~' | 'like' | 'ilike';
+    value: string | number | Date | boolean | null;
+}
+/** Internal interface defining operators available to *array values* */
+interface ArraySearchFilter<Schema, Table extends string & keyof Schema> {
+    name: string & keyof Schema[Table];
+    field?: string;
+    op: 'in' | 'not in';
+    value: (string | number | Date | boolean | null)[];
+}
+/** Internal interface defining operators available to *json values* */
+interface JsonSearchFilter<Schema, Table extends string & keyof Schema> {
+    name: string & keyof Schema[Table];
+    field?: never;
+    op: '@>' | '<@';
+    value: any;
+}
+/**
+ * A filter for a search that matches a single value
+ *
+ * - `name` is the column name to filter on
+ * - `field` is a field to filter on when the column is a complex type (JSONB)
+ * - `op` is the operator to use for the filter (default: `=`)
+ * - `value` is the value to filter for
+ *
+ * All operators are defined as per PostgreSQL documentation, with few notable
+ * exceptions:
+ *
+ * - `~` is an alias to the `ilike` operator
+ * - `in` and `not in` are used to match a value against an array of possible
+ *   values using the `... = ANY(...)`  or `... != ALL(...)` constructs
+ * - `@>` and `<@` will accept single values as well as arrays.
+ * - `!=` and `=` will use the PostgreSQL `IS (NOT) DISTINCT FROM` semantics
+ *   to properly handle `NULL` comparisons.
+ */
+export type SearchFilter<Schema, Table extends string & keyof Schema> = Prettify<ValueSearchFilter<Schema, Table>> | Prettify<ArraySearchFilter<Schema, Table>> | Prettify<JsonSearchFilter<Schema, Table>>;
+/**
+ * Base interface for querying results via our {@link Search}.
+ */
+export type SearchQuery<Schema, Table extends string & keyof Schema, Joins extends SearchJoins<Schema>> = Prettify<{
+    /** An optional set of filters to apply */
+    filters?: Prettify<SearchFilter<Schema, Table>[]>;
+    /** An optional column to sort by */
+    sort?: string & (keyof Schema[Table] | SortableJoins<Joins>);
+    /** The order to sort by (if `sort` is specified, default: 'asc') */
+    order?: 'asc' | 'desc';
+    /** An optional full-text search query, available for full-text search */
+    q?: string;
+}>;
+/**
+ * Full options for querying a limited set of results via our {@link Search}.
+ */
+export type SearchOptions<Schema, Table extends string & keyof Schema, Joins extends SearchJoins<Schema>> = Prettify<SearchQuery<Schema, Table, Joins> & {
+    /** Offset to start returning rows from (default: 0) */
+    offset?: number;
+    /** Maximum number of rows to return (default: 20, unlimited if 0) */
+    limit?: number;
+}>;
+/** A single search result row (with joins) */
+export type SearchResult<Schema, Table extends string & keyof Schema, Joins extends SearchJoins<Schema> = {}> = Prettify<Schema[Table] extends Record<string, ColumnDefinition> ? InferSelectType<Schema[Table]> & {
+    [key in keyof Joins]: Joins[key]['refTable'] extends keyof Schema ? Schema[Joins[key]['refTable']] extends Record<string, ColumnDefinition> ? Schema[Table][Joins[key]['column']]['isNullable'] extends true ? Prettify<InferSelectType<Schema[Joins[key]['refTable']]>> | null : Prettify<InferSelectType<Schema[Joins[key]['refTable']]>> : unknown : unknown;
+} : never>;
+/** What's being returned by our `search` */
+export interface SearchResults<Schema, Table extends string & keyof Schema, Joins extends SearchJoins<Schema> = {}> {
+    /** The total length of all available results (without offset or limit) */
+    total: number;
+    /** The lines queried (truncated by offset and limit) */
+    rows: SearchResult<Schema, Table, Joins>[];
+}
+export {};

package/dist/search.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=search.mjs.map

package/dist/search.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": [],
+  "mappings": "",
+  "names": []
+}

package/dist/utils.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// utils.ts
+var utils_exports = {};
+module.exports = __toCommonJS(utils_exports);
+//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../src/utils.ts"],
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+/** Prettify a type by flattening intersections */
+export type Prettify<T extends object> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Extract only the string keys from a type */
+export type OnlyStrings<T> = T extends string ? T : never;

package/dist/utils.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": [],
+  "mappings": "",
+  "names": []
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@juit/pgproxy-model",
+  "version": "0.0.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "scripts": {},
+  "author": "Juit Developers <developers@juit.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/juitnow/juit-pgproxy.git"
+  },
+  "keywords": [
+    "database",
+    "pg",
+    "pool",
+    "postgres",
+    "proxy"
+  ],
+  "bugs": {
+    "url": "https://github.com/juitnow/juit-pgproxy/issues"
+  },
+  "homepage": "https://github.com/juitnow/juit-pgproxy#readme",
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "*.md",
+    "dist/",
+    "src/"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type * from './model'
+export type * from './search'

package/src/model.ts

@@ -0,0 +1,77 @@
+import type { OnlyStrings, Prettify } from './utils'
+
+/* ========================================================================== *
+ * TYPE INFERENCE: FROM SCHEMA->TABLE->COLUMN->... TO JS TYPES                *
+ * ========================================================================== */
+
+/** The definition of a column */
+export interface ColumnDefinition<T = any> {
+  /** The TypeScript type of the column (from the type parser) */
+  type: T,
+  /** Whether the column is _generated_ or not */
+  isGenerated?: boolean,
+  /** Whether the column is _nullable_ or not */
+  isNullable?: boolean,
+  /** Whether the column _specifies a default value_ or not */
+  hasDefault?: boolean,
+}
+
+/** Infer the TypeScript type suitable for an `INSERT` in a table */
+export type InferInsertType<Table extends Record<string, ColumnDefinition>> = Prettify<{
+  /* First part: all nullable or defaulted columns are optional */
+  [ Column in keyof Table as Column extends string
+    ? Table[Column]['isGenerated'] extends true ? never
+    : Table[Column]['isNullable'] extends true ? Column
+    : Table[Column]['hasDefault'] extends true ? Column
+    : never
+    : never
+  ] ? :
+  Table[Column]['isNullable'] extends true
+    ? Table[Column]['type'] | null
+    : Table[Column]['type']
+} & {
+  /* Second part: all non-nullable or non-defaulted columns are required */
+  [ Column in keyof Table as Column extends string
+    ? Table[Column]['isGenerated'] extends true ? never
+    : Table[Column]['isNullable'] extends true ? never
+    : Table[Column]['hasDefault'] extends true ? never
+    : Column
+    : never
+  ] -? :
+  Table[Column]['isNullable'] extends true
+    ? Table[Column]['type'] | null
+    : Table[Column]['type']
+}>
+
+/** Infer the TypeScript type suitable for a `SELECT` from a table */
+export type InferSelectType<Table extends Record<string, ColumnDefinition>> = {
+  [ Column in keyof Table as Column extends string ? Column : never ] -? :
+    ( Table[Column]['isNullable'] extends true
+      ? Table[Column]['type'] | null
+      : Table[Column]['type']
+    ) & ( Table[Column] extends { branding: infer Brand } ? Brand : unknown )
+}
+
+/** Infer the TypeScript type suitable for a `UPDATE` in a table */
+export type InferUpdateType<Table extends Record<string, ColumnDefinition>> = {
+  [ Column in keyof Table as Column extends string
+    ? Table[Column]['isGenerated'] extends true ? never
+    : Column
+    : never
+  ] ? :
+  Table[Column]['isNullable'] extends true
+    ? Table[Column]['type'] | null
+    : Table[Column]['type']
+}
+
+/** Infer the TypeScript type used for querying records */
+export type InferQueryType<Table extends Record<string, ColumnDefinition>> ={
+  [ Column in keyof Table as Column extends string ? Column : never ] ? :
+  Table[Column]['isNullable'] extends true
+    ? Table[Column]['type'] | null
+    : Table[Column]['type']
+}
+
+/** Infer the available sort values for a table (as required by `ORDER BY`) */
+export type InferSort<Table extends Record<string, ColumnDefinition>> =
+  `${OnlyStrings<keyof Table>}${' ASC' | ' asc' | ' DESC' | ' desc' | ''}`

package/src/search.ts

@@ -0,0 +1,194 @@
+import type { ColumnDefinition, InferSelectType } from './model'
+import type { Prettify } from './utils'
+
+/** Simple type to extract joins with a specified sortcolumn */
+type SortableJoins<Joins> = keyof {
+  [ key in keyof Joins as Joins[key] extends { sortColumn: string } ? key : never ] : undefined
+}
+
+/* ========================================================================== *
+ * JOINS                                                                      *
+ * ========================================================================== */
+
+/**
+ * Definition for a simple (straight) join in a {@link Search}
+ */
+export interface SearchJoin<Schema> {
+  /**
+   * The column in _the search table_ (passed to the constructor of
+   * {@link Search}) referencing the specified `refTable` (defined here).
+   *
+   * ```sql
+   * ... LEFT JOIN "refTable" ON "table"."column" = "refTable"."refColumn"
+   *                                      ^^^^^^
+   * ```
+   */
+  column: string
+  /**
+   * The name of the table to _left join_.
+   *
+   * ```sql
+   * ... LEFT JOIN "refTable" ON "table"."column" = "refTable"."refColumn"
+   *                ^^^^^^^^                         ^^^^^^^^
+   * ```
+   */
+  refTable: string & keyof Schema
+  /**
+   * The column in the `refTable` referenced by the _the search table_.
+   *
+   * ```sql
+   * ... LEFT JOIN "refTable" ON "table"."column" = "refTable"."refColumn"
+   *                                                            ^^^^^^^^^
+   * ```
+   */
+  refColumn: string
+  /**
+   * The column in the referenced table to use as default sort column, when
+   * sorting by this join.
+   */
+  sortColumn?: string
+}
+
+/**
+ * Definition for joins in a {@link Search}
+ *
+ * Each key is the name of the join as it will appear in the results, and the
+ * value defines how to perform the join.
+ *
+ * See {@link StraightJoin} and {@link LinkedJoin} for details on the fields.
+ */
+export interface SearchJoins<Schema> {
+  [ key: string ]: SearchJoin<Schema>
+}
+
+/* ========================================================================== *
+ * SEARCH OPTIONS                                                             *
+ * ========================================================================== */
+
+/** Internal interface defining operators available to *single values* */
+interface ValueSearchFilter<
+  Schema,
+  Table extends string & keyof Schema,
+> {
+  name: string & keyof Schema[Table]
+  field?: string
+  op?: '=' | '!=' | '>' | '>=' | '<' | '<=' | '~' | 'like' | 'ilike'
+  value: string | number | Date | boolean | null
+}
+
+/** Internal interface defining operators available to *array values* */
+interface ArraySearchFilter<
+  Schema,
+  Table extends string & keyof Schema,
+> {
+  name: string & keyof Schema[Table]
+  field?: string
+  op: 'in' | 'not in'
+  value: (string | number | Date | boolean | null)[]
+}
+
+/** Internal interface defining operators available to *json values* */
+interface JsonSearchFilter<
+  Schema,
+  Table extends string & keyof Schema,
+> {
+  name: string & keyof Schema[Table]
+  field?: never
+  op: '@>' | '<@'
+  value: any
+}
+
+/**
+ * A filter for a search that matches a single value
+ *
+ * - `name` is the column name to filter on
+ * - `field` is a field to filter on when the column is a complex type (JSONB)
+ * - `op` is the operator to use for the filter (default: `=`)
+ * - `value` is the value to filter for
+ *
+ * All operators are defined as per PostgreSQL documentation, with few notable
+ * exceptions:
+ *
+ * - `~` is an alias to the `ilike` operator
+ * - `in` and `not in` are used to match a value against an array of possible
+ *   values using the `... = ANY(...)`  or `... != ALL(...)` constructs
+ * - `@>` and `<@` will accept single values as well as arrays.
+ * - `!=` and `=` will use the PostgreSQL `IS (NOT) DISTINCT FROM` semantics
+ *   to properly handle `NULL` comparisons.
+ */
+export type SearchFilter<
+  Schema,
+  Table extends string & keyof Schema,
+> = Prettify<ValueSearchFilter<Schema, Table>>
+  | Prettify<ArraySearchFilter<Schema, Table>>
+  | Prettify<JsonSearchFilter<Schema, Table>>
+
+/**
+ * Base interface for querying results via our {@link Search}.
+ */
+export type SearchQuery<
+  Schema,
+  Table extends string & keyof Schema,
+  Joins extends SearchJoins<Schema>,
+> = Prettify<{
+  /** An optional set of filters to apply */
+  filters?: Prettify<SearchFilter<Schema, Table>[]>
+  /** An optional column to sort by */
+  sort?: string & (keyof Schema[Table] | SortableJoins<Joins>)
+  /** The order to sort by (if `sort` is specified, default: 'asc') */
+  order?: 'asc' | 'desc'
+  /** An optional full-text search query, available for full-text search */
+  q?: string
+}>
+
+/**
+ * Full options for querying a limited set of results via our {@link Search}.
+ */
+export type SearchOptions<
+  Schema,
+  Table extends string & keyof Schema,
+  Joins extends SearchJoins<Schema>,
+> = Prettify<SearchQuery<Schema, Table, Joins> & {
+  /** Offset to start returning rows from (default: 0) */
+  offset?: number
+  /** Maximum number of rows to return (default: 20, unlimited if 0) */
+  limit?: number
+}>
+
+/* ========================================================================== *
+ * SEARCH RESULTS                                                             *
+ * ========================================================================== */
+
+/** A single search result row (with joins) */
+export type SearchResult<
+  Schema,
+  Table extends string & keyof Schema,
+  Joins extends SearchJoins<Schema> = {},
+> = Prettify<
+  Schema[Table] extends Record<string, ColumnDefinition> ?
+  // This is the main table's column field
+  InferSelectType<Schema[Table]> & {
+    // For each join, add a field with the joined table's inferred type
+    [ key in keyof Joins ] : Joins[key]['refTable'] extends keyof Schema ?
+      // If the column referencing this join is nullable, the result can be null
+      Schema[Joins[key]['refTable']] extends Record<string, ColumnDefinition> ?
+        Schema[Table][Joins[key]['column']]['isNullable'] extends true ?
+          Prettify<InferSelectType<Schema[Joins[key]['refTable']]>> | null :
+          Prettify<InferSelectType<Schema[Joins[key]['refTable']]>> :
+        // If the joined table isn't a column def, we can't infer anything
+        unknown :
+      // If the table doesn't exist in the schema, we can't infer anything
+      unknown
+  } : never>
+
+/** What's being returned by our `search` */
+export interface SearchResults<
+  Schema,
+  Table extends string & keyof Schema,
+  Joins extends SearchJoins<Schema> = {},
+> {
+  /** The total length of all available results (without offset or limit) */
+  total: number
+  /** The lines queried (truncated by offset and limit) */
+  rows: SearchResult<Schema, Table, Joins>[]
+}

package/src/utils.ts

@@ -0,0 +1,4 @@
+/** Prettify a type by flattening intersections */
+export type Prettify<T extends object> = { [ K in keyof T ]: T[K] } & {}
+/** Extract only the string keys from a type */
+export type OnlyStrings<T> = T extends string ? T : never