@rwillians/qx 0.1.20 → 0.2.0

package/dist/esm/standard-schema.js

@@ -0,0 +1,235 @@
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                       STANDARD SCHEMA SPEC                        //
+// // // // // // // // // // // // // // // // // // // // // // // //
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                        STANDARD SCHEMA API                        //
+// // // // // // // // // // // // // // // // // // // // // // // //
+/**
+ * @public  The Standard Schema interface.
+ * @since   0.1.0
+ * @version 1
+ */
+export {};
+/**
+ * @public  Use any standard schema to parse a value.
+ * @since   0.1.0
+ * @version 1
+ */
+export const parse = (schema, value) => {
+    const parsed = schema['~standard'].validate(value);
+    if (parsed instanceof Promise) {
+        throw new Error('async standard schema validators are not supported');
+    }
+    return parsed;
+};
+// // // // // // // // // // // // // // // // // // // // // // // //
+//                               UTILS                               //
+// // // // // // // // // // // // // // // // // // // // // // // //
+const prependPath = (path) => (issue) => ({
+    ...issue,
+    path: [path, ...(issue.path ?? [])],
+});
+/**
+ * @public  Defines an array of a given standard schema.
+ * @since   0.1.0
+ * @version 1
+ */
+export const array = (schema) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => {
+            if (!Array.isArray(input)) {
+                return { issues: [{ message: 'must be an array' }] };
+            }
+            const issues = [];
+            const value = [];
+            for (let i = 0; i < input.length; i++) {
+                const parsed = parse(schema, input[i]);
+                parsed.issues
+                    ? issues.push(...parsed.issues.map(prependPath(i)))
+                    : value.push(parsed.value);
+            }
+            return issues.length > 0
+                ? { issues }
+                : { value: value };
+        },
+    },
+});
+/**
+ * @public  Defines a standard schema for boolean values.
+ * @since   0.1.0
+ * @version 1
+ */
+export const boolean = () => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => typeof input !== 'boolean'
+            ? { issues: [{ message: 'must be a boolean' }] }
+            : { value: input },
+    },
+});
+/**
+ * @public  Defines a standard schema for Date values that can be
+ *          coerced from ISO 8601 strings or epoch timestamps in
+ *          milliseconds.
+ * @since   0.1.0
+ * @version 1
+ */
+export const date = () => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => {
+            if (input instanceof Date)
+                return isNaN(input.getTime())
+                    ? { issues: [{ message: 'must be a valid date' }] }
+                    : { value: input };
+            if (typeof input !== 'string' &&
+                typeof input !== 'number')
+                return { issues: [{ message: 'must be a valid ISO 8601 string or epoch timestamp in milliseconds' }] };
+            const date = new Date(input);
+            if (isNaN(date.getTime()))
+                return { issues: [{ message: 'must be a valid ISO 8601 string or epoch timestamp in milliseconds' }] };
+            return { value: date };
+        },
+    },
+});
+/**
+ * @public  Defines a standard schema that validates instances of a
+ *          given class.
+ * @since   0.1.0
+ * @version 1
+ */
+export const instanceOf = (ctor) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => !(input instanceof ctor)
+            ? { issues: [{ message: `must be an instance of ${ctor.name}` }] }
+            : { value: input },
+    },
+});
+/**
+ * @public  Defines a standard schema for integers with optional min and max constraints.
+ * @since   0.1.0
+ * @version 1
+ */
+export const integer = ({ min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER } = {}) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => {
+            if (typeof input !== 'number')
+                return { issues: [{ message: 'must be a integer' }] };
+            if (Number.isNaN(input) || !Number.isFinite(input))
+                return { issues: [{ message: 'must be a integer' }] };
+            if (!Number.isInteger(input))
+                return { issues: [{ message: 'must be a integer' }] };
+            if (input < min)
+                return { issues: [{ message: `must be greater than or equal to ${min}` }] };
+            if (input > max)
+                return { issues: [{ message: `must be less than or equal to ${max}` }] };
+            return { value: input };
+        },
+    },
+});
+/**
+ * @public  Makes any standard schema accepts `null` as a valid value.
+ * @since   0.1.0
+ * @version 1
+ */
+export const nullable = (schema) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (value) => value === null
+            ? { value }
+            : parse(schema, value),
+    },
+});
+/**
+ * @public  Defines a standard schema for numbers with optional min
+ *          and max constraints.
+ * @since   0.1.0
+ * @version 1
+ */
+export const number = ({ min = Number.MIN_VALUE, max = Number.MAX_VALUE } = {}) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => {
+            if (typeof input !== 'number')
+                return { issues: [{ message: 'must be a number' }] };
+            if (Number.isNaN(input) || !Number.isFinite(input))
+                return { issues: [{ message: 'must be a number' }] };
+            if (input < min)
+                return { issues: [{ message: `must be greater than or equal to ${min}` }] };
+            if (input > max)
+                return { issues: [{ message: `must be less than or equal to ${max}` }] };
+            return { value: input };
+        },
+    },
+});
+/**
+ * @public  Defines an object schema that does not allow extra fields.
+ * @since   0.1.0
+ * @version 1
+ */
+export const strictObject = (shape) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => {
+            if (typeof input !== 'object' || input === null) {
+                return { issues: [{ message: 'must be an object' }] };
+            }
+            const issues = [];
+            const inputKeys = new Set(Object.keys(input));
+            const shapeKeys = new Set(Object.keys(shape));
+            // one issue for each key of `input` that doesn't exist in `shape`
+            for (const key of inputKeys.difference(shapeKeys)) {
+                issues.push({ path: [key], message: 'unknown field' });
+            }
+            // one issue for each key of `shape` that doesn't exist in `input`
+            for (const key of shapeKeys.difference(inputKeys)) {
+                issues.push({ path: [key], message: 'is required' });
+            }
+            const record = {};
+            for (const [key, value] of Object.entries(input)) {
+                const parsed = shape[key]['~standard'].validate(value);
+                if (parsed instanceof Promise) {
+                    throw new Error('async validators are not supported');
+                }
+                parsed.issues
+                    ? issues.push(...parsed.issues.map(prependPath(key)))
+                    : record[key] = parsed.value;
+            }
+            return issues.length > 0
+                ? { issues }
+                : { value: record };
+        },
+    },
+});
+/**
+ * @public  Defines a standard schema for strings with optional min
+ *          and max length constraints.
+ * @since   0.1.0
+ * @version 1
+ */
+export const string = ({ min, max } = {}) => ({
+    '~standard': {
+        version: 1,
+        vendor: 'qx',
+        validate: (input) => {
+            if (typeof input !== 'string')
+                return { issues: [{ message: 'must be a string' }] };
+            if (min !== undefined && input.length < min)
+                return { issues: [{ message: `must be at least ${min} characters long` }] };
+            if (max !== undefined && input.length > max)
+                return { issues: [{ message: `must be at most ${max} characters long` }] };
+            return { value: input };
+        },
+    },
+});

package/dist/esm/utils.js

@@ -0,0 +1,79 @@
+/**
+ * @private Converts a snake_case string to camelCase.
+ * @since   0.1.0
+ * @version 2
+ */
+export const camelCase = (str) => str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+/**
+ * @private Same as {@link Object.prototype.entries} but with better
+ *          types.
+ * @since   0.1.17
+ * @version 1
+ */
+export const entries = (obj) => Object.entries(obj);
+/**
+   * @private Simplified check for plain objects.
+   * @since   0.1.0
+   * @version 1
+   */
+export const isPlainObject = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    let proto = Object.getPrototypeOf(value);
+    if (proto === null)
+        return true;
+    return proto === Object.prototype;
+};
+/**
+ * @private Same as {@link Object.prototype.keys} but with better
+ *          types.
+ * @since   0.1.17
+ * @version 1
+ */
+export const keys = (obj) => Object.keys(obj);
+/**
+   * @private Throws an error if the given number is greater than the
+   *          specified maximum.
+   * @since   0.1.0
+   * @version 1
+   */
+export const lte = (n, max) => {
+    if (n > max)
+        throw new Error(`Must be at most ${max}, got ${n}`);
+    return n;
+};
+/**
+ * @public  Maps over the keys of an object.
+ * @since   0.1.0
+ * @version 1
+ */
+export const mapKeys = (obj, fn) => Object.fromEntries(entries(obj).map(([key, value]) => [fn(key), value]));
+/**
+ * @private Maps over the values of an object.
+ * @since   0.1.0
+ * @version 1
+ */
+export const mapValues = (obj, fn) => Object.fromEntries(entries(obj).map(([key, value]) => [key, fn(value, key)]));
+/**
+   * @private Resolves the given value or function to a value.
+   * @since   0.1.0
+   * @version 1
+   */
+export const resolve = (value) => typeof value === 'function'
+    ? value()
+    : value;
+/**
+ * @private Converts a camelCase string to snake_case.
+ * @since   0.1.0
+ * @version 1
+ */
+export const snakeCase = (str) => str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+/**
+   * @public  Wraps the given value in an array, unless it's already an
+   *          array.
+   * @since   0.1.0
+   * @version 1
+   */
+export const wrap = (value) => Array.isArray(value)
+    ? value
+    : [value];

package/dist/types/adapter.d.ts

@@ -0,0 +1,16 @@
+import { type ILogger } from './index';
+/**
+ * @public  Wraps a function call that executes DDL with logging
+ *          capabilities.
+ *
+ *          A `debug` log is emitted before the function is executed,
+ *          and an `error` log if the function throws an error. After
+ *          logging, the error is re-thrown.
+ * @since   0.1.17
+ * @version 1
+ */
+export declare const withLoggedQuery: <T>(logger: ILogger | ILogger[], data: {
+    sql: string;
+    params: any[];
+}, fn: (sql: string, params: any[]) => Promise<T> | T) => Promise<T>;
+export { type CodecsRegistry, type Column, type CreateTableStatement, type DDL, type DeleteStatement, type Expr, type ExprAnd, type ExprBinaryOp, type ExprLiteral, type ExprNot, type ExprOr, type IDatabase, type ILogger, type InsertStatement, type Join, type OrderDirection, type PrimitiveToNativeTypeFactory, type SelectStatement, is, } from './index';

package/dist/types/bun-sqlite.d.ts

@@ -0,0 +1,65 @@
+import { Database } from 'bun:sqlite';
+import { type CreateTableStatement, type DeleteStatement, type IDatabase, type ILogger, type InsertStatement, type SelectStatement } from './adapter';
+/**
+ * @private Bun SQLite database adapter implementation.
+ * @since   0.1.0
+ * @version 1
+ */
+declare class BunSQLite implements IDatabase {
+    private conn;
+    private loggers;
+    constructor(conn: Database, loggers?: ILogger[]);
+    /**
+     * @public  Attaches a logger to the database instance.
+     * @since   0.1.0
+     * @version 1
+     */
+    attachLogger(logger: ILogger): this;
+    /**
+     * @public  Executes a delete statement.
+     * @since   0.1.22
+     * @version 1
+     */
+    delete(op: DeleteStatement): Promise<number>;
+    /**
+     * @public  Executes a create table statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    createTable(op: CreateTableStatement): Promise<void>;
+    /**
+     * @public  Executes an insert statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    insert(op: InsertStatement): Promise<{
+        [k: string]: any;
+    }[]>;
+    /**
+     * @public  Executes a select statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    query(op: SelectStatement): Promise<{
+        [k: string]: any;
+    }[]>;
+    /**
+     * @public  Executes a function within a transaction.
+     * @since   0.1.10
+     * @version 1
+     */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * @public  Creates a connection to the database.
+ * @since   0.1.0
+ * @version 1
+ */
+declare const connect: (...args: ConstructorParameters<typeof Database>) => BunSQLite;
+/**
+ * @public  Creates a connection to an in-memory database.
+ * @since   0.1.12
+ * @version 2
+ */
+declare const inmemory: () => BunSQLite;
+export { connect, inmemory, };

package/dist/types/console-logger.d.ts

@@ -0,0 +1,21 @@
+import { type ILogger } from './index';
+/**
+ * @public  Creates a basic console logger that pretty-prints queries.
+ *
+ *          Pretty printing is enabled by default but you can disable
+ *          it to print plain-text instead (no ASCII styling), just
+ *          set the option `pretty` to `false`.
+ * @since   0.1.0
+ * @version 3
+ *
+ * @example
+ * ```ts
+ * import { createConsoleLogger } from '@rwillians/qx/console-logger';
+ *
+ * const prettyLogger = createConsoleLogger();
+ * const plainLogger = createConsoleLogger({ pretty: false });
+ * ```
+ */
+export declare const createConsoleLogger: (opts?: {
+    pretty: boolean;
+}) => ILogger;

package/dist/types/experimental-migrations.d.ts

@@ -0,0 +1,63 @@
+import { type IDatabase, type Table } from './index';
+/**
+ * @public  Create statement builder.
+ * @since   0.1.0
+ * @version 1
+ */
+export declare const create: {
+    /**
+     * @public  Prepares a create table statement.
+     * @since   0.1.0
+     * @version 1
+     */
+    table: <T extends Table, S extends {
+        ifNotExists?: true;
+        unlogged?: true;
+    }>(table: T, options?: S) => {
+        /**
+         * @public  Executes the create table statement onto the given
+         *          database.
+         * @since   0.1.0
+         * @version 1
+         */
+        onto: (db: IDatabase) => Promise<void>;
+    };
+};
+/**
+ * @private Defines the type for a migration function.
+ * @since   0.1.6
+ * @version 1
+ */
+type Migration = (db: IDatabase) => Promise<void>;
+/**
+ * @public  Defines a set of migrations to be executed against a
+ *          database.
+ * @since   0.1.6
+ * @version 2
+ *
+ * @example
+ * ```ts
+ * // src/db/migrations.ts
+ * import { create, defineMigrations } from '@rwillians/qx/experimental-migrations';
+ * import { users } from './users';
+ * import { profiles } from './profiles';
+ *
+ * export const migrate = defineMigrations({
+ *   '0001': async (db) => {
+ *     await create.table(users).onto(db);
+ *   },
+ *   '0002': async (db) => {
+ *     await create.table(profiles).onto(db);
+ *   },
+ * });
+ *
+ * // src/index.ts
+ * import * as sqlite from '@rwillians/qx/bun-sqlite';
+ * import { migrate } from './db/migrations';
+ *
+ * const db = sqlite.connect('./db.sqlite');
+ * await migrate(db)
+ * ```
+ */
+export declare const defineMigrations: (migs: Record<string, Migration>) => (db: IDatabase) => Promise<void>;
+export {};