@abw/badger-database/dist/Utils/Columns.d.ts

Javascript database abstraction layer

import { TableColumn, TableColumnFragments, TableColumns, TableColumnSpec, TableColumnsSpec, TableSpec } from '../types';
/**
 * Function to convert an array of column specification fragments into a
 * well-structured `TableColumn` object.
 * @example
 * ```ts
 * const column = prepareColumnSpecFragments(
 *   'artists', 'id',
 *   ['readonly', 'type=number'],
 * })
 * ```
 * Returns:
 * ```ts
 * {
 *   column: 'id',
 *   tableColumn: 'artists.id',
 *   readonly: true,
 *   type: 'number'
 * }
 * ```
 **/
export declare const prepareColumnFragments: (table: string, column: string, fragments: TableColumnFragments) => TableColumn;
/**
 * Splits a string containing colon-separated column specification fragments
 * into an array, validating that they are all valid `TableColumnFragment`
 * strings.  Returns a `TableColumnFragments` array or throws an error.
 * @example
 * ```ts
 * const fragments = splitColumnSpecFragments(
 *   'artists', 'id',
 *   'readonly:type=number'
 * )
 * ```
 * Returns:
 * ```ts
 * [ 'readonly', 'type=number']
 * ```
 **/
export declare const splitColumnFragments: (table: string, column: string, spec: string) => TableColumnFragments;
export declare const throwInvalidColumnFragments: (table: string, column: string, spec: string, fragments: string[]) => void;
/**
 * Prepares a column specification, validating it for correctness as either
 * a string containing one or more `TableColumnFragment` parts separated by
 * colons, or a `TableSpec` object (a `Partial<TableColumn>`) containing valid
 * keys that can be upgraded to a `TableColumn` object.  Throws an error if
 * the `spec` is invalid.
 * @example
 * Specifying a string of column fragments
 * ```ts
 * const column = prepareColumn(
 *   'artists', 'id',
 *   'readonly:type=number'
 * )
 * ```
 * Returns:
 * ```ts
 * {
 *    column: 'id',
 *    tableColumn: 'artists.id',
 *    readonly: true,
 *    type: 'number'
 * }
 * ```
 * @example
 * Specifying an object containing a partial `TableColumn` specification
 * ```ts
 * const column = prepareColumn(
 *   'artists', 'id',
 *   { readonly: true, type: 'number' }
 * )
 * ```
 * Returns:
 * ```ts
 * {
 *    column: 'id',
 *    tableColumn: 'artists.id',
 *    readonly: true,
 *    type: 'number'
 * }
 * ```
 **/
export declare const prepareColumn: (table: string, column: string, spec: TableColumnSpec) => TableColumn;
/**
 * Function to prepare column definitions for a table.  If the columns specified
 * are a string of whitespace delimited tokens then they are first split into an
 * array.  An array is converted to a hash object by splitting each item on the
 * first colon, e.g. `id:required` has the column name `id` and flags of `required`.
 * Each value is then converted to an object, e.g. `required` becomes `{ required: true }`.
 * Then end result is an object where the keys are the column names and corresponding
 * values are objects containing any flags defined for the column.
 * @example
 * Specifying `columns` as a string of column names
 * ```ts
 * const columns = prepareColumns(
 *   'artists',
 *   'id name'
 * )
 * ```
 * @example
 * Specifying `columns` as a string of column names and modifiers
 * ```ts
 * const columns = prepareColumns(
 *   'artists',
 *   'id:readonly name:required'
 * )
 * ```
 * @example
 * Specifying `columns` as an array of names with optional modifiers
 * ```ts
 * const columns = prepareColumns(
 *   'artists',
 *   ['id:readonly', 'name:required']
 * )
 * ```
 * @example
 * Specifying `columns` as an object with string as values
 * ```ts
 * const columns = prepareColumns({
 *   table: 'artists',
 *   columns: {
 *     id:   'readonly',
 *     name: 'required'
 *   }
 * })
 * ```
 * @example
 * Specifying `columns` as an object with objects as values
 * ```ts
 * const columns = prepareColumns({
 *   table: 'artists',
 *   columns: {
 *     id:   { readonly: true },
 *     name: { required: true }
 *   }
 * })
 * ```
 */
export declare const prepareColumns: (table: string, columns: TableColumnsSpec) => TableColumns;
/**
 * Function to prepare column definitions for a table, where the `columns` are
 * specified as a whitespace delimited string of column names with optional
 * modifiers.
 * @example
 * Specifying `columns` as a string of column names
 * ```ts
 * const columns = prepareColumns(
 *   'artists',
 *   'id name'
 * )
 * ```
 * @example
 * Specifying `columns` as a string of column names and modifiers
 * ```ts
 * const columns = prepareColumns(
 *   'artists',
 *   'id:readonly name:required'
 * )
 * ```
 **/
export declare const prepareColumnsString: (table: string, columns: string) => TableColumns;
/**
 * Function to prepare column definitions for a table, where the `columns` are
 * specified as an array of strings containing column names with optional
 * modifiers.
 * @example
 * ```ts
 * const columns = prepareColumnsArray(
 *   'artists',
 *   ['id', 'name:required:type=string']
 * )
 * ```
 **/
export declare const prepareColumnsArray: (table: string, columns: string[]) => TableColumns;
/**
 * Function to prepare column definitions for a table, where the `columns` are
 * specified as an object with keys for column names and values containing
 * any valid column specification
 * modifiers.
 * @example
 * ```ts
 * const columns = prepareColumnsObject(
 *   'artists',
 *   {
 *     id: 'readonly:type=number',
 *     name: { required: true, type: 'string' }
 *   }
 * )
 * ```
 **/
export declare const prepareColumnsObject: (table: string, columns: TableColumnsSpec) => TableColumns;
/**
 * Function to determine the id and/or keys columns for a table.
 * If an `id` column is explicitly listed in the schema then it is assumed
 * to be the single id column which is both the (single entry) array of keys
 * and the id.  Otherwise we look for all the columns (hopefully no more than
 * one) that have the `id` flag set.  If there is more than one then an error
 * is thrown.  Failing that it looks for either an explicit list of keys in
 * the table specification (either a whitespace delimited string of column
 * names or array of column name strings), or all the columns that have the
 * `key` flag set.  If none of those cases hold then the default `id` key is
 * assumed.
 * @example
 * Specifying an explicit `id` column in the schema
 * ```ts
 * const { id, keys } = prepareKeys(
 *   'artists',
 *   {
 *     id: 'artist_id', // explicit id column
 *   },
 *   {
 *     artist_id: { type: 'number', required: true, readonly: true },
 *     name:      { type: 'string', required: true },
 *   },
 * )
 * ```
 * @example
 * Specifying an explicit array of `keys` column in the schema
 * ```ts
 * const { id, keys } = prepareKeys(
 *   'artists',
 *   {
 *     keys: ['label_id', 'artist_id'], // explicit keys array
 *   },
 *   {
 *     label_id:  { type: 'number', required: true },
 *     artist_id: { type: 'number', required: true, readonly: true },
 *     name:      { type: 'string', required: true },
 *   },
 * )
 * ```
 * @example
 * Specifying a column with the `id` flag set
 * ```ts
 * const { id, keys } = prepareKeys(
 *   'artists',
 *   { ... },
 *   {
 *     artist_id: { type: 'number', required: true, readonly: true, id: true },
 *     name:      { type: 'string', required: true },
 *   }
 * )
 * @example
 * Specifying the `key` flag on one or more columns
 * ```ts
 * const { id, keys } = prepareKeys(
 *   'artists',
 *   { ... },
 *   {
 *     label_id:  { type: 'number', required: true, key: true },
 *     artist_id: { type: 'number', required: true, readonly: true, key: true },
 *     name:      { type: 'string', required: true },
 *   },
 * )
 * ```
 */
export declare const prepareKeys: (table: string, spec: TableSpec, columns: TableColumns) => {
    keys: string[];
    id: string;
} | {
    keys: string[];
    id?: undefined;
};
//# sourceMappingURL=Columns.d.ts.map