neosqlite 1.0.0

package/src/migrations/commands/up.ts

@@ -0,0 +1,56 @@
+import fs from "fs/promises";
+import { CliCommandOptions } from "../../types";
+
+import type { MigrationFile } from "..";
+
+import { createClient } from "../../client";
+import { createMigrationTableIfNotExists, logSuccess, logWarn, validateMigrationDirectory } from "../util";
+
+export default async function Up({ migrationPath, migrationTable, ...config }: CliCommandOptions) {
+  const db = createClient(config);
+
+  await validateMigrationDirectory(migrationPath);
+  createMigrationTableIfNotExists(db, migrationTable);
+
+  // Query all of the migrations that have already been ran
+  const result = db.read("SELECT filepath FROM " + migrationTable);
+  const migratedFiles = result.map((row) => String(row["filepath"]));
+
+  const files = await fs.readdir(migrationPath);
+  const migrationFiles = files.filter((file) => {
+    const fileName = file.split(".")[0];
+    return (file.endsWith(".ts") || file.endsWith(".js")) && !migratedFiles.includes(fileName);
+  });
+
+  if (!migrationFiles.length) {
+    logWarn("No migrations to run");
+    process.exit(0);
+  }
+
+  // Sort the files by timestamp, in ascending order so that they run in the order they were created
+  migrationFiles.sort((a, b) => {
+    const aTimestamp = parseInt(a.split("_")[0]);
+    const bTimestamp = parseInt(b.split("_")[0]);
+    return aTimestamp - bTimestamp;
+  });
+
+  // Apply the migrations
+  for (const fileName of migrationFiles) {
+    const migration: MigrationFile = (await import(`${migrationPath}/${fileName}`)).default;
+    const normalizedFileName = fileName.split(".")[0];
+
+    // Run the migration
+    db.transaction(() => migration.up(db));
+
+    // Store the migration data
+    db.write({
+      sql: "INSERT INTO " + migrationTable + "(filepath, timestamp) VALUES (:filepath, :timestamp)",
+      args: { filepath: normalizedFileName, timestamp: Date.now() },
+    });
+
+    logSuccess(`Applied migration ${fileName}`);
+  }
+
+  logSuccess(`Successfully ran ${migrationFiles.length} migration(s)`);
+  process.exit(0);
+}

package/src/migrations/index.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+
+import Up from "./commands/up";
+import New from "./commands/new";
+import Down from "./commands/down";
+
+import packageJSON from "../../package.json";
+import { CliCommandOptions, NeosqliteClient } from "../types";
+
+export interface MigrationFile {
+  up: (db: NeosqliteClient) => void;
+  down: (db: NeosqliteClient) => void;
+}
+
+export function createNeosqliteMigrationCli(props: CliCommandOptions) {
+  props.migrationTable = props.migrationTable ?? "migrations";
+
+  const program = new Command();
+
+  program.name("migrate").description("Migration CLI").version(packageJSON.version);
+
+  program
+    .command("up")
+    .description("Apply all unapplied migrations")
+    .action(() => Up(props));
+
+  program
+    .command("down")
+    .description("Undo the last migration")
+    .action(() => Down(props));
+
+  program
+    .command("new")
+    .option("-n, --name <name>", "The name of the migration")
+    .action((options) => {
+      if (!options.name) {
+        console.error("Please provide a name for the migration. Use the --name flag");
+        process.exit(1);
+      }
+
+      New({ ...props, name: options.name });
+    });
+
+  program.parse(process.argv);
+}

package/src/migrations/util.ts

@@ -0,0 +1,46 @@
+import fs from "fs/promises";
+
+import { NeosqliteClient } from "../types";
+import { queryString } from "../client/util";
+
+const RESET = "\x1b[0m";
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+
+const CHECK = "✔";
+const CROSS = "✖";
+const WARN = "⚠";
+
+export const logSuccess = (message: string) => {
+  console.log(`${GREEN}${CHECK}${RESET} ${message}`);
+};
+
+export const logError = (message: string) => {
+  console.log(`${RED}${CROSS}${RESET} ${message}`);
+};
+
+export const logWarn = (message: string) => {
+  console.log(`${YELLOW}${WARN}${RESET} ${message}`);
+};
+
+export const createMigrationTableIfNotExists = (db: NeosqliteClient, migrationTable: string = "migrations") => {
+  return db.write({
+    sql: queryString(
+      "CREATE TABLE IF NOT EXISTS " + migrationTable + "(",
+      "  id INTEGER PRIMARY KEY AUTOINCREMENT,",
+      "  filepath TEXT,",
+      "  timestamp INTEGER",
+      ")",
+    ),
+  });
+};
+
+export const validateMigrationDirectory = async (migrationPath: string) => {
+  try {
+    await fs.access(migrationPath);
+  } catch (e) {
+    logError("Unable to find the migration directory. Make sure it exists");
+    process.exit(0);
+  }
+};

package/src/types.ts

@@ -0,0 +1,98 @@
+import type { BackupMetadata, BackupOptions, PragmaOptions } from "better-sqlite3";
+
+export type NeosqliteConfig = {
+  /** The filename of the database */
+  file: ":memory:" | string;
+
+  /** When a query is logged using `logQuery: true`, you will receive the full query string via this callback */
+  onQueryLog?: (query: string) => void;
+
+  /** When a query finishes, gather data about the query from this callback */
+  onQueryComplete?: (data: OnQueryFinishData) => void;
+};
+
+export type NeosqliteClient = {
+  /** Call a pragma */
+  pragma: (source: string, options?: PragmaOptions | undefined) => unknown;
+
+  /** Backup the database */
+  backup: (destinationFile: string, options?: BackupOptions | undefined) => Promise<BackupMetadata>;
+
+  /** Create a transaction and execute queries within it */
+  transaction: (fn: Function) => void;
+
+  /** Read data from the database, returns all matching rows */
+  read: (params: ExecuteQueryParams) => Row[];
+
+  /** Read data from the database, returns the first matching row */
+  readOne: (params: ExecuteQueryParams) => Row | undefined;
+
+  /** Write data to the database, returns all matching rows via RETURNING */
+  writeReturning: (params: ExecuteQueryParams) => Row[];
+
+  /** Write data to the database, returns the number of rows affected */
+  write: (params: ExecuteQueryParams) => { changes: number; lastInsertedRowid: number };
+};
+
+export type OnQueryFinishData = {
+  /** The query that was executed */
+  query: string;
+
+  /** The time it took to execute the query in milliseconds */
+  time: number;
+};
+
+export type QueryParams = {
+  /** The SQL query to execute */
+  sql: string;
+
+  /** When true, the query string will be sent to onQueryLog */
+  logQuery?: boolean;
+
+  /** The values to bind to the query string */
+  args?: Record<string, number | string | boolean | null>;
+};
+
+export type Row = Record<string, number | string | boolean | null>;
+
+export type ExecuteQueryParams = string | QueryParams;
+
+export enum JobPriority {
+  Low = 1,
+  Medium = 2,
+  High = 3,
+}
+
+export enum JobStatus {
+  Pending = "pending",
+  Running = "running",
+  Failed = "failed",
+  Completed = "completed",
+}
+
+export interface CliCommandOptions extends NeosqliteConfig {
+  /** The path containing the migration files */
+  migrationPath: string;
+
+  /** The name of the table to store migrations in. Defaults to "migrations" */
+  migrationTable?: string;
+}
+
+export interface CreateJobsOptions extends NeosqliteConfig {
+  /** The name of the table to store jobs in. Defaults to "jobs" */
+  jobsTable?: string;
+
+  /** How often to process jobs in milliseconds. Defaults to 5000 */
+  processEvery?: number;
+
+  /** The maximum number of retries for each job. Defaults to 3 */
+  maxRetries?: number;
+
+  /** The maximum number of jobs to execute at once. Defaults to 10 */
+  maxJobs?: number;
+}
+
+export interface JobOptions {
+  /** The priority of the job */
+  priority?: number;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./lib",
+    "strict": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}