Document typedefs better. Fix tables deletion schema sync issue.

dist/commands/schema.js

@@ -7,6 +7,7 @@ import dbSchemaToTypeDef from "../lib/sqlite/schema-to-typedef";
 import _ from "lodash";
 import appendDefaultFieldsToDbSchema from "../utils/append-default-fields-to-db-schema";
 import chalk from "chalk";
+import { writeLiveSchema } from "../functions/live-schema";
 export default function () {
     return new Command("schema")
         .description("Build DB From Schema")
@@ -33,6 +34,7 @@ export default function () {
                 config,
             });
         }
+        writeLiveSchema({ schema: finaldbSchema });
         console.log(`${chalk.bold(chalk.green(`DB Schema setup success!`))}`);
         process.exit();
     });

dist/data/grab-dir-names.d.ts

@@ -1,3 +1,11 @@
-export default function grabDirNames(): {
+import type { BunSQLiteConfig } from "../types";
-    ROOT_DIR: string;
+type Params = {
+    config?: BunSQLiteConfig;
 };
+export default function grabDirNames(params?: Params): {
+    ROOT_DIR: string;
+    BUN_SQLITE_DIR: string;
+    BUN_SQLITE_TEMP_DIR: string;
+    BUN_SQLITE_LIVE_SCHEMA: string;
+};
+export {};

dist/data/grab-dir-names.js

@@ -1,7 +1,13 @@
 import path from "path";
-export default function grabDirNames() {
+export default function grabDirNames(params) {
     const ROOT_DIR = process.cwd();
+    const BUN_SQLITE_DIR = path.join(ROOT_DIR, ".bun-sqlite");
+    const BUN_SQLITE_TEMP_DIR = path.join(BUN_SQLITE_DIR, ".tmp");
+    const BUN_SQLITE_LIVE_SCHEMA = path.join(BUN_SQLITE_DIR, "live-schema.json");
     return {
         ROOT_DIR,
+        BUN_SQLITE_DIR,
+        BUN_SQLITE_TEMP_DIR,
+        BUN_SQLITE_LIVE_SCHEMA,
     };
 }

dist/functions/live-schema.d.ts

@@ -0,0 +1,7 @@
+import type { BUN_SQLITE_DatabaseSchemaType } from "../types";
+type Params = {
+    schema: BUN_SQLITE_DatabaseSchemaType;
+};
+export declare function writeLiveSchema({ schema }: Params): void;
+export declare function readLiveSchema(): BUN_SQLITE_DatabaseSchemaType | undefined;
+export {};

dist/functions/live-schema.js

@@ -0,0 +1,15 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import grabDirNames from "../data/grab-dir-names";
+import path from "path";
+const { BUN_SQLITE_LIVE_SCHEMA } = grabDirNames();
+export function writeLiveSchema({ schema }) {
+    mkdirSync(path.dirname(BUN_SQLITE_LIVE_SCHEMA), { recursive: true });
+    writeFileSync(BUN_SQLITE_LIVE_SCHEMA, JSON.stringify(schema));
+}
+export function readLiveSchema() {
+    if (!existsSync(BUN_SQLITE_LIVE_SCHEMA)) {
+        return undefined;
+    }
+    const live_schema = readFileSync(BUN_SQLITE_LIVE_SCHEMA, "utf-8");
+    return JSON.parse(live_schema);
+}

dist/lib/sqlite/db-schema-manager.js

@@ -3,6 +3,7 @@ import { Database } from "bun:sqlite";
 import _ from "lodash";
 import DbClient from ".";
 import { AppData } from "../../data/app-data";
+import { readLiveSchema } from "../../functions/live-schema";
 // Schema Manager Class
 class SQLiteSchemaManager {
     db;
@@ -60,8 +61,21 @@ class SQLiteSchemaManager {
      * Drop tables that are no longer in the schema
      */
     async dropRemovedTables(existingTables, schemaTables) {
+        console.log(`Cleaning up tables ...`);
         const tablesToDrop = existingTables.filter((t) => !schemaTables.includes(t) &&
             !schemaTables.find((scT) => t.startsWith(scT + "_")));
+        const currentSchema = readLiveSchema();
+        if (currentSchema?.tables?.[0]) {
+            for (let i = 0; i < currentSchema.tables.length; i++) {
+                const table = currentSchema.tables[i];
+                if (!table?.tableName)
+                    continue;
+                const does_table_exist = schemaTables.find((t) => t == table.tableName);
+                if (!does_table_exist) {
+                    tablesToDrop.push(table.tableName);
+                }
+            }
+        }
         for (const tableName of tablesToDrop) {
             console.log(`Dropping table: ${tableName}`);
             this.db.run(`DROP TABLE IF EXISTS "${tableName}"`);

dist/types/index.d.ts

@@ -1,6 +1,18 @@
 import type { RequestOptions } from "https";
+/**
+ * Fully-qualified database name used when a database needs to be referenced
+ * across local and remote operations.
+ */
 export type BUN_SQLITE_DatabaseFullName = string;
+/**
+ * User fields that should be omitted from general-purpose payloads and public
+ * responses.
+ */
 export declare const UsersOmitedFields: readonly ["password", "social_id", "verification_status", "date_created", "date_created_code", "date_created_timestamp", "date_updated", "date_updated_code", "date_updated_timestamp"];
+/**
+ * Describes an entire database schema, including its tables and clone/child
+ * database metadata.
+ */
 export interface BUN_SQLITE_DatabaseSchemaType {
     id?: string | number;
     dbName?: string;
@@ -15,10 +27,21 @@ export interface BUN_SQLITE_DatabaseSchemaType {
     updateData?: boolean;
     collation?: (typeof MariaDBCollations)[number];
 }
+/**
+ * Minimal reference to a child database linked to a parent database schema.
+ */
 export interface BUN_SQLITE_ChildrenDatabaseObject {
     dbId?: string | number;
 }
+/**
+ * Supported MariaDB collations that can be applied at the database or table
+ * level.
+ */
 export declare const MariaDBCollations: readonly ["utf8mb4_bin", "utf8mb4_unicode_520_ci"];
+/**
+ * Describes a single table within a database schema, including its fields,
+ * indexes, unique constraints, and parent/child table relationships.
+ */
 export interface BUN_SQLITE_TableSchemaType {
     id?: string | number;
     tableName: string;
@@ -58,13 +81,22 @@ export interface BUN_SQLITE_TableSchemaType {
      */
     childTableDbId?: string | number;
     collation?: (typeof MariaDBCollations)[number];
+    /**
+     * If this is a vector table
+     */
     isVector?: boolean;
     vectorType?: string;
 }
+/**
+ * Reference object used to link a table to one of its child tables.
+ */
 export interface BUN_SQLITE_ChildrenTablesType {
     tableId?: string | number;
     dbId?: string | number;
 }
+/**
+ * Supported editor/content modes for text fields.
+ */
 export declare const TextFieldTypesArray: readonly [{
     readonly title: "Plain Text";
     readonly value: "plain";
@@ -96,6 +128,9 @@ export declare const TextFieldTypesArray: readonly [{
     readonly title: "Code";
     readonly value: "code";
 }];
+/**
+ * Core SQLite column types supported by the schema builder.
+ */
 export declare const BUN_SQLITE_DATATYPES: readonly [{
     readonly value: "TEXT";
 }, {
@@ -105,6 +140,10 @@ export declare const BUN_SQLITE_DATATYPES: readonly [{
 }, {
     readonly value: "REAL";
 }];
+/**
+ * Describes a table column, including SQL constraints, text editor options,
+ * vector metadata, and foreign key configuration.
+ */
 export type BUN_SQLITE_FieldSchemaType = {
     id?: number | string;
     fieldName?: string;
@@ -171,6 +210,9 @@ WHERE embedding MATCH ? AND k = 1;
 } & {
     [key in (typeof TextFieldTypesArray)[number]["value"]]?: boolean;
 };
+/**
+ * Defines a foreign key relationship from one field to another table column.
+ */
 export interface BUN_SQLITE_ForeignKeyType {
     foreignKeyName?: string;
     destinationTableName?: string;
@@ -179,6 +221,9 @@ export interface BUN_SQLITE_ForeignKeyType {
     cascadeDelete?: boolean;
     cascadeUpdate?: boolean;
 }
+/**
+ * Describes a table index and the fields it covers.
+ */
 export interface BUN_SQLITE_IndexSchemaType {
     id?: string | number;
     indexName?: string;
@@ -187,19 +232,31 @@ export interface BUN_SQLITE_IndexSchemaType {
     alias?: string;
     newTempIndex?: boolean;
 }
+/**
+ * Describes a multi-field uniqueness rule for a table.
+ */
 export interface BUN_SQLITE_UniqueConstraintSchemaType {
     id?: string | number;
     constraintName?: string;
     alias?: string;
     constraintTableFields?: BUN_SQLITE_UniqueConstraintFieldType[];
 }
+/**
+ * Single field reference inside a unique constraint definition.
+ */
 export interface BUN_SQLITE_UniqueConstraintFieldType {
     value: string;
 }
+/**
+ * Field metadata used when generating SQL for indexes.
+ */
 export interface BUN_SQLITE_IndexTableFieldType {
     value: string;
     dataType: string;
 }
+/**
+ * Result shape returned by MySQL `SHOW INDEXES` queries.
+ */
 export interface BUN_SQLITE_MYSQL_SHOW_INDEXES_Type {
     Key_name: string;
     Table: string;
@@ -210,6 +267,9 @@ export interface BUN_SQLITE_MYSQL_SHOW_INDEXES_Type {
     Index_comment: string;
     Comment: string;
 }
+/**
+ * Result shape returned by MySQL `SHOW COLUMNS` queries.
+ */
 export interface BUN_SQLITE_MYSQL_SHOW_COLUMNS_Type {
     Field: string;
     Type: string;
@@ -218,6 +278,9 @@ export interface BUN_SQLITE_MYSQL_SHOW_COLUMNS_Type {
     Default: string;
     Extra: string;
 }
+/**
+ * Result shape returned by MariaDB `SHOW INDEXES` queries.
+ */
 export interface BUN_SQLITE_MARIADB_SHOW_INDEXES_TYPE {
     Table: string;
     Non_unique: 0 | 1;
@@ -233,11 +296,18 @@ export interface BUN_SQLITE_MARIADB_SHOW_INDEXES_TYPE {
     Index_comment?: string;
     Ignored?: "YES" | "NO";
 }
+/**
+ * Minimal metadata returned when listing MySQL foreign keys.
+ */
 export interface BUN_SQLITE_MYSQL_FOREIGN_KEYS_Type {
     CONSTRAINT_NAME: string;
     CONSTRAINT_SCHEMA: string;
     TABLE_NAME: string;
 }
+/**
+ * Database record describing a user-owned database and optional remote sync
+ * metadata.
+ */
 export interface BUN_SQLITE_MYSQL_user_databases_Type {
     id: number;
     user_id: number;
@@ -261,12 +331,18 @@ export interface BUN_SQLITE_MYSQL_user_databases_Type {
     last_name?: string;
     email?: string;
 }
+/**
+ * Return value used when converting an uploaded image file to base64.
+ */
 export type ImageInputFileToBase64FunctionReturn = {
     imageBase64?: string;
     imageBase64Full?: string;
     imageName?: string;
     imageSize?: number;
 };
+/**
+ * Querystring parameters accepted by generic GET data endpoints.
+ */
 export interface GetReqQueryObject {
     db: string;
     query: string;
@@ -274,6 +350,9 @@ export interface GetReqQueryObject {
     tableName?: string;
     debug?: boolean;
 }
+/**
+ * Canonical logged-in user shape shared across auth, session, and API flows.
+ */
 export type DATASQUIREL_LoggedInUser = {
     id: number;
     uuid?: string;
@@ -295,6 +374,9 @@ export type DATASQUIREL_LoggedInUser = {
 } & {
     [key: string]: any;
 };
+/**
+ * Standard authenticated-user response wrapper.
+ */
 export interface AuthenticatedUser {
     success: boolean;
     payload: DATASQUIREL_LoggedInUser | null;
@@ -302,18 +384,27 @@ export interface AuthenticatedUser {
     userId?: number;
     cookieNames?: any;
 }
+/**
+ * Minimal successful user payload returned by user creation flows.
+ */
 export interface SuccessUserObject {
     id: number;
     first_name: string;
     last_name: string;
     email: string;
 }
+/**
+ * Return type for helpers that create a user record.
+ */
 export interface AddUserFunctionReturn {
     success: boolean;
     payload?: SuccessUserObject | null;
     msg?: string;
     sqlResult?: any;
 }
+/**
+ * Shape exposed by the Google Identity prompt lifecycle callback.
+ */
 export interface GoogleIdentityPromptNotification {
     getMomentType: () => string;
     getDismissedReason: () => string;
@@ -325,6 +416,9 @@ export interface GoogleIdentityPromptNotification {
     isNotDisplayed: () => boolean;
     isSkippedMoment: () => boolean;
 }
+/**
+ * User data accepted by registration and profile-creation flows.
+ */
 export type UserDataPayload = {
     first_name: string;
     last_name: string;
@@ -334,6 +428,9 @@ export type UserDataPayload = {
 } & {
     [key: string]: any;
 };
+/**
+ * Return shape for helpers that fetch a single user.
+ */
 export interface GetUserFunctionReturn {
     success: boolean;
     payload: {
@@ -349,6 +446,9 @@ export interface GetUserFunctionReturn {
         verification_status: [number];
     } | null;
 }
+/**
+ * Return type for reauthentication flows that refresh auth state.
+ */
 export interface ReauthUserFunctionReturn {
     success: boolean;
     payload: DATASQUIREL_LoggedInUser | null;
@@ -356,10 +456,16 @@ export interface ReauthUserFunctionReturn {
     userId?: number;
     token?: string;
 }
+/**
+ * Return type for user update helpers.
+ */
 export interface UpdateUserFunctionReturn {
     success: boolean;
     payload?: Object[] | string;
 }
+/**
+ * Generic success/error wrapper for read operations.
+ */
 export interface GetReturn<R extends any = any> {
     success: boolean;
     payload?: R;
@@ -368,6 +474,9 @@ export interface GetReturn<R extends any = any> {
     schema?: BUN_SQLITE_TableSchemaType;
     finalQuery?: string;
 }
+/**
+ * Query parameters used when requesting schema metadata.
+ */
 export interface GetSchemaRequestQuery {
     database?: string;
     table?: string;
@@ -377,10 +486,19 @@ export interface GetSchemaRequestQuery {
         [k: string]: string;
     };
 }
+/**
+ * API credential payload used when a schema request must be authenticated.
+ */
 export interface GetSchemaAPICredentialsParam {
     key: string;
 }
+/**
+ * Complete request object for authenticated schema fetches.
+ */
 export type GetSchemaAPIParam = GetSchemaRequestQuery & GetSchemaAPICredentialsParam;
+/**
+ * Generic response wrapper for write operations.
+ */
 export interface PostReturn {
     success: boolean;
     payload?: Object[] | string | PostInsertReturn;
@@ -388,6 +506,9 @@ export interface PostReturn {
     error?: any;
     schema?: BUN_SQLITE_TableSchemaType;
 }
+/**
+ * High-level CRUD payload accepted by server-side data mutation handlers.
+ */
 export interface PostDataPayload {
     action: "insert" | "update" | "delete";
     table: string;
@@ -398,17 +519,27 @@ export interface PostDataPayload {
     duplicateColumnValue?: string;
     update?: boolean;
 }
+/**
+ * Local-only variant of `PostReturn` used by in-process operations.
+ */
 export interface LocalPostReturn {
     success: boolean;
     payload?: any;
     msg?: string;
     error?: string;
 }
+/**
+ * Query object for local write operations that may accept raw SQL or a CRUD
+ * payload.
+ */
 export interface LocalPostQueryObject {
     query: string | PostDataPayload;
     tableName?: string;
     queryValues?: string[];
 }
+/**
+ * Insert/update metadata returned by SQL drivers after a write completes.
+ */
 export interface PostInsertReturn {
     fieldCount?: number;
     affectedRows?: number;
@@ -420,24 +551,36 @@ export interface PostInsertReturn {
     changedRows?: number;
     error?: string;
 }
+/**
+ * Extended user object used within the application runtime.
+ */
 export type UserType = DATASQUIREL_LoggedInUser & {
     isSuperUser?: boolean;
     staticHost?: string;
     appHost?: string;
     appName?: string;
 };
+/**
+ * Stored API key definition and its associated metadata.
+ */
 export interface ApiKeyDef {
     name: string;
     scope: string;
     date_created: string;
     apiKeyPayload: string;
 }
+/**
+ * Aggregate dashboard metrics shown in admin and overview screens.
+ */
 export interface MetricsType {
     dbCount: number;
     tablesCount: number;
     mediaCount: number;
     apiKeysCount: number;
 }
+/**
+ * Shape of the internal MariaDB users table.
+ */
 export interface MYSQL_mariadb_users_table_def {
     id?: number;
     user_id?: number;
@@ -453,13 +596,26 @@ export interface MYSQL_mariadb_users_table_def {
     date_updated_code?: number;
     date_updated_timestamp?: string;
 }
+/**
+ * Credentials used to connect to a MariaDB instance as a specific user.
+ */
 export interface MariaDBUserCredType {
     mariadb_user?: string;
     mariadb_host?: string;
     mariadb_pass?: string;
 }
+/**
+ * Supported logical operators for server-side query generation.
+ */
 export declare const ServerQueryOperators: readonly ["AND", "OR"];
+/**
+ * Supported comparison operators for server-side query generation.
+ */
 export declare const ServerQueryEqualities: readonly ["EQUAL", "LIKE", "LIKE_RAW", "LIKE_LOWER", "LIKE_LOWER_RAW", "NOT LIKE", "NOT LIKE_RAW", "NOT_LIKE_LOWER", "NOT_LIKE_LOWER_RAW", "NOT EQUAL", "REGEXP", "FULLTEXT", "IN", "NOT IN", "BETWEEN", "NOT BETWEEN", "IS NULL", "IS NOT NULL", "EXISTS", "NOT EXISTS", "GREATER THAN", "GREATER THAN OR EQUAL", "LESS THAN", "LESS THAN OR EQUAL", "MATCH", "MATCH_BOOLEAN"];
+/**
+ * Top-level query-builder input used to generate SELECT statements, joins,
+ * grouping, pagination, and full-text search clauses.
+ */
 export type ServerQueryParam<T extends {
     [k: string]: any;
 } = {
@@ -483,6 +639,9 @@ export type ServerQueryParam<T extends {
     fullTextSearch?: ServerQueryParamFullTextSearch<T>;
     [key: string]: any;
 };
+/**
+ * Represents a single `GROUP BY` field, optionally qualified by table name.
+ */
 export type ServerQueryParamGroupBy<T extends {
     [k: string]: any;
 } = {
@@ -491,6 +650,9 @@ export type ServerQueryParamGroupBy<T extends {
     field: keyof T;
     table?: string;
 };
+/**
+ * Represents a single `ORDER BY` clause.
+ */
 export type ServerQueryParamOrder<T extends {
     [k: string]: any;
 } = {
@@ -499,6 +661,10 @@ export type ServerQueryParamOrder<T extends {
     field: keyof T;
     strategy: "ASC" | "DESC";
 };
+/**
+ * Configuration for a full-text search query and the alias used for the score
+ * column.
+ */
 export type ServerQueryParamFullTextSearch<T extends {
     [k: string]: any;
 } = {
@@ -509,6 +675,9 @@ export type ServerQueryParamFullTextSearch<T extends {
     /** Field Name to user to Rank the Score of Search Results */
     scoreAlias: string;
 };
+/**
+ * Describes a count subquery that is projected into the main SELECT result.
+ */
 export type ServerQueryParamsCount = {
     table: string;
     /** Alias for the Table From which the count is fetched */
@@ -519,10 +688,16 @@ export type ServerQueryParamsCount = {
     }[];
     alias: string;
 };
+/**
+ * Source/target mapping used inside count subqueries.
+ */
 export type ServerQueryParamsCountSrcTrgMap = {
     table: string;
     field: string;
 };
+/**
+ * Declares a selected field and an optional alias for the result set.
+ */
 export type TableSelectFieldsObject<T extends {
     [k: string]: any;
 } = {
@@ -531,6 +706,10 @@ export type TableSelectFieldsObject<T extends {
     fieldName: keyof T;
     alias?: string;
 };
+/**
+ * Value wrapper used when a query condition needs per-value metadata such as a
+ * custom equality or explicit table/field names.
+ */
 export type ServerQueryValuesObject = {
     value?: string | number;
     /**
@@ -540,7 +719,14 @@ export type ServerQueryValuesObject = {
     tableName?: string;
     fieldName?: string;
 };
+/**
+ * All value shapes accepted by a query condition, including arrays used by
+ * operators such as `IN` and `BETWEEN`.
+ */
 export type ServerQueryObjectValue = string | number | ServerQueryValuesObject | undefined | null | (string | number | ServerQueryValuesObject | undefined | null)[];
+/**
+ * Describes a single query condition and any nested subconditions for a field.
+ */
 export type ServerQueryObject<T extends object = {
     [key: string]: any;
 }, K extends string = string> = {
@@ -566,11 +752,18 @@ export type ServerQueryObject<T extends object = {
      */
     vectorFunction?: string;
 };
+/**
+ * Field-to-condition map for server-side query generation.
+ */
 export type ServerQueryQueryObject<T extends object = {
     [key: string]: any;
 }, K extends string = string> = {
     [key in keyof T]: ServerQueryObject<T, K>;
 };
+/**
+ * Parameters for authenticated fetch helpers used by the frontend and internal
+ * SDK layers.
+ */
 export type FetchDataParams = {
     path: string;
     method?: (typeof DataCrudRequestMethods)[number];
@@ -578,9 +771,15 @@ export type FetchDataParams = {
     query?: AuthFetchQuery;
     tableName?: string;
 };
+/**
+ * Query object accepted by authenticated data-fetch helpers.
+ */
 export type AuthFetchQuery = ServerQueryParam & {
     [key: string]: any;
 };
+/**
+ * Join clause definition used by the server query builder.
+ */
 export type ServerQueryParamsJoin<Table extends string = string, Field extends object = {
     [key: string]: any;
 }> = {
@@ -600,6 +799,9 @@ export type ServerQueryParamsJoin<Table extends string = string, Field extends o
     })[];
     operator?: (typeof ServerQueryOperators)[number];
 };
+/**
+ * Defines how a root-table field maps to a join-table field in an `ON` clause.
+ */
 export type ServerQueryParamsJoinMatchObject<Field extends object = {
     [key: string]: any;
 }> = {
@@ -614,10 +816,16 @@ export type ServerQueryParamsJoinMatchObject<Field extends object = {
         operator: "AND" | "OR";
     };
 };
+/**
+ * Explicit table/field reference for join match definitions.
+ */
 export type ServerQueryParamsJoinMatchSourceTargetObject = {
     tableName: string;
     fieldName: string;
 };
+/**
+ * Payload used when pushing or pulling a schema to or from a remote API.
+ */
 export type ApiConnectBody = {
     url: string;
     key: string;
@@ -626,6 +834,9 @@ export type ApiConnectBody = {
     type: "pull" | "push";
     user_id?: string | number;
 };
+/**
+ * Superuser credentials and auth state.
+ */
 export type SuUserType = {
     email: string;
     password: string;
@@ -633,6 +844,10 @@ export type SuUserType = {
     logged_in_status: boolean;
     date: number;
 };
+/**
+ * Configuration for a remote MariaDB host in replicated or load-balanced
+ * setups.
+ */
 export type MariadbRemoteServerObject = {
     host: string;
     port: number;
@@ -640,11 +855,17 @@ export type MariadbRemoteServerObject = {
     loadBalanced?: boolean;
     users?: MariadbRemoteServerUserObject[];
 };
+/**
+ * Credentials for a user provisioned on a remote MariaDB server.
+ */
 export type MariadbRemoteServerUserObject = {
     name: string;
     password: string;
     host: string;
 };
+/**
+ * Standard login response returned by API authentication helpers.
+ */
 export type APILoginFunctionReturn = {
     success: boolean;
     msg?: string;
@@ -655,6 +876,9 @@ export type APILoginFunctionReturn = {
     csrf?: string;
     cookieNames?: any;
 };
+/**
+ * Parameters required to create a user through the public API layer.
+ */
 export type APICreateUserFunctionParams = {
     encryptionKey?: string;
     payload: any;
@@ -662,7 +886,13 @@ export type APICreateUserFunctionParams = {
     dsqlUserID?: string | number;
     verify?: boolean;
 };
+/**
+ * Function signature for API user-creation handlers.
+ */
 export type APICreateUserFunction = (params: APICreateUserFunctionParams) => Promise<AddUserFunctionReturn>;
+/**
+ * Result returned when reconciling a social login with the local user store.
+ */
 export type HandleSocialDbFunctionReturn = {
     success: boolean;
     user?: DATASQUIREL_LoggedInUser | null;
@@ -674,6 +904,9 @@ export type HandleSocialDbFunctionReturn = {
     newUser?: any;
     error?: any;
 } | null;
+/**
+ * Cookie definition used when setting auth/session cookies.
+ */
 export type CookieObject = {
     name: string;
     value: string;
@@ -686,6 +919,9 @@ export type CookieObject = {
     sameSite?: "Strict" | "Lax" | "None";
     priority?: "Low" | "Medium" | "High";
 };
+/**
+ * Request options accepted by the generic HTTP client helper.
+ */
 export type HttpRequestParams<ReqObj extends {
     [k: string]: any;
 } = {
@@ -696,6 +932,9 @@ export type HttpRequestParams<ReqObj extends {
     query?: ReqObj;
     urlEncodedFormBody?: boolean;
 };
+/**
+ * Function signature for the generic HTTP request helper.
+ */
 export type HttpRequestFunction<ReqObj extends {
     [k: string]: any;
 } = {
@@ -705,6 +944,9 @@ export type HttpRequestFunction<ReqObj extends {
 } = {
     [k: string]: any;
 }> = (param: HttpRequestParams<ReqObj>) => Promise<HttpFunctionResponse<ResObj>>;
+/**
+ * Normalized response returned by the generic HTTP request helper.
+ */
 export type HttpFunctionResponse<ResObj extends {
     [k: string]: any;
 } = {
@@ -716,6 +958,9 @@ export type HttpFunctionResponse<ResObj extends {
     str?: string;
     requestedPath?: string;
 };
+/**
+ * GET request payload for API data reads.
+ */
 export type ApiGetQueryObject<T extends {
     [k: string]: any;
 } = {
@@ -725,8 +970,18 @@ export type ApiGetQueryObject<T extends {
     table: string;
     dbFullName?: string;
 };
+/**
+ * Uppercase HTTP methods supported by the CRUD helpers.
+ */
 export declare const DataCrudRequestMethods: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+/**
+ * Lowercase variant of the supported HTTP methods, used where string casing
+ * must match external APIs.
+ */
 export declare const DataCrudRequestMethodsLowerCase: readonly ["get", "post", "put", "patch", "delete", "options"];
+/**
+ * Runtime parameters passed to generic CRUD handlers.
+ */
 export type DsqlMethodCrudParam<T extends {
     [key: string]: any;
 } = {
@@ -751,6 +1006,9 @@ export type DsqlMethodCrudParam<T extends {
     }) => T | T[];
     debug?: boolean;
 };
+/**
+ * Hook used to mutate input data before a CRUD action is executed.
+ */
 export type DsqlCrudTransformDataFunction<T extends {
     [key: string]: any;
 } = {
@@ -761,6 +1019,9 @@ export type DsqlCrudTransformDataFunction<T extends {
     existingData?: T;
     reqMethod: (typeof DataCrudRequestMethods)[number];
 }) => Promise<T>;
+/**
+ * Hook used to mutate query input before a CRUD action is executed.
+ */
 export type DsqlCrudTransformQueryFunction<T extends {
     [key: string]: any;
 } = {
@@ -770,7 +1031,13 @@ export type DsqlCrudTransformQueryFunction<T extends {
     user?: DATASQUIREL_LoggedInUser;
     reqMethod: (typeof DataCrudRequestMethods)[number];
 }) => Promise<DsqlCrudQueryObject<T>>;
+/**
+ * High-level CRUD actions supported by the DSQL helpers.
+ */
 export declare const DsqlCrudActions: readonly ["insert", "update", "delete", "get"];
+/**
+ * Query object used by CRUD helpers, built on top of the server query builder.
+ */
 export type DsqlCrudQueryObject<T extends {
     [key: string]: any;
 } = {
@@ -778,6 +1045,9 @@ export type DsqlCrudQueryObject<T extends {
 }, K extends string = string> = ServerQueryParam<T, K> & {
     query?: ServerQueryQueryObject<T, K>;
 };
+/**
+ * Parameters used to generate a SQL `DELETE` statement.
+ */
 export type SQLDeleteGeneratorParams<T extends {
     [key: string]: any;
 } = {
@@ -789,6 +1059,9 @@ export type SQLDeleteGeneratorParams<T extends {
     dbFullName?: string;
     data?: any;
 };
+/**
+ * Single key/value predicate used by the delete SQL generator.
+ */
 export type SQLDeleteData<T extends {
     [key: string]: any;
 } = {
@@ -798,69 +1071,39 @@ export type SQLDeleteData<T extends {
     value: string | number | null | undefined;
     operator?: (typeof ServerQueryEqualities)[number];
 };
+/**
+ * Prebuilt SQL where-clause fragment and its bound parameters.
+ */
 export type DsqlCrudParamWhereClause = {
     clause: string;
     params?: string[];
 };
+/**
+ * Callback signature used when surfacing internal errors to callers.
+ */
 export type ErrorCallback = (title: string, error: Error, data?: any) => void;
-export interface MariaDBUser {
+/**
-    Host?: string;
+ * Reserved query parameter names used throughout the API layer.
-    User?: string;
+ */
-    Password?: string;
-    Select_priv?: string;
-    Insert_priv?: string;
-    Update_priv?: string;
-    Delete_priv?: string;
-    Create_priv?: string;
-    Drop_priv?: string;
-    Reload_priv?: string;
-    Shutdown_priv?: string;
-    Process_priv?: string;
-    File_priv?: string;
-    Grant_priv?: string;
-    References_priv?: string;
-    Index_priv?: string;
-    Alter_priv?: string;
-    Show_db_priv?: string;
-    Super_priv?: string;
-    Create_tmp_table_priv?: string;
-    Lock_tables_priv?: string;
-    Execute_priv?: string;
-    Repl_slave_priv?: string;
-    Repl_client_priv?: string;
-    Create_view_priv?: string;
-    Show_view_priv?: string;
-    Create_routine_priv?: string;
-    Alter_routine_priv?: string;
-    Create_user_priv?: string;
-    Event_priv?: string;
-    Trigger_priv?: string;
-    Create_tablespace_priv?: string;
-    Delete_history_priv?: string;
-    ssl_type?: string;
-    ssl_cipher?: string;
-    x509_issuer?: string;
-    x509_subject?: string;
-    max_questions?: number;
-    max_updates?: number;
-    max_connections?: number;
-    max_user_connections?: number;
-    plugin?: string;
-    authentication_string?: string;
-    password_expired?: string;
-    is_role?: string;
-    default_role?: string;
-    max_statement_time?: number;
-}
 export declare const QueryFields: readonly ["duplicate", "user_id", "delegated_user_id", "db_id", "table_id", "db_slug"];
+/**
+ * Minimal representation of a local folder entry.
+ */
 export type LocalFolderType = {
     name: string;
     isPrivate: boolean;
 };
+/**
+ * SQL string and bound parameters produced during query generation.
+ */
 export type ResponseQueryObject = {
     sql?: string;
     params?: (string | number)[];
 };
+/**
+ * Common API response wrapper used by data, auth, media, and utility
+ * endpoints.
+ */
 export type APIResponseObject<T extends {
     [k: string]: any;
 } = {
@@ -906,10 +1149,19 @@ export type DockerCompose = {
     networks: DockerComposeNetworks;
     name: string;
 };
+/**
+ * Supported Docker Compose service names used by the deployment helpers.
+ */
 export declare const DockerComposeServices: readonly ["setup", "cron", "reverse-proxy", "webapp", "websocket", "static", "db", "maxscale", "post-db-setup", "web-app-post-db-setup", "post-replica-db-setup", "db-replica-1", "db-replica-2", "db-cron", "web-app-post-db-setup"];
+/**
+ * Map of compose service names to service definitions.
+ */
 export type DockerComposeServicesType = {
     [key in (typeof DockerComposeServices)[number]]: DockerComposeServiceWithBuildObject;
 };
+/**
+ * Docker Compose network definitions.
+ */
 export type DockerComposeNetworks = {
     [k: string]: {
         driver?: "bridge";
@@ -919,10 +1171,16 @@ export type DockerComposeNetworks = {
         external?: boolean;
     };
 };
+/**
+ * Static network config for a Docker Compose network.
+ */
 export type DockerComposeNetworkConfigObject = {
     subnet: string;
     gateway: string;
 };
+/**
+ * Service definition for compose services that are built from source.
+ */
 export type DockerComposeServiceWithBuildObject = {
     build: DockerComposeServicesBuildObject;
     env_file: string;
@@ -940,24 +1198,39 @@ export type DockerComposeServiceWithBuildObject = {
     };
     user?: string;
 };
+/**
+ * Service definition for compose services that use a prebuilt image.
+ */
 export type DockerComposeServiceWithImage = Omit<DockerComposeServiceWithBuildObject, "build"> & {
     image: string;
 };
+/**
+ * Build instructions for a Docker Compose service.
+ */
 export type DockerComposeServicesBuildObject = {
     context: string;
     dockerfile: string;
 };
+/**
+ * Per-network addressing information for a Docker Compose service.
+ */
 export type DockerComposeServiceNetworkObject = {
     [k: string]: {
         ipv4_address: string;
     };
 };
+/**
+ * Metadata recorded for a table cloned from another database.
+ */
 export type ClonedTableInfo = {
     dbId?: string | number;
     tableId?: string | number;
     keepUpdated?: boolean;
     keepDataUpdated?: boolean;
 };
+/**
+ * Common columns present on default/generated table entries.
+ */
 export type DefaultEntryType = {
     id?: number;
     uuid?: string;
@@ -970,29 +1243,55 @@ export type DefaultEntryType = {
 } & {
     [k: string]: string | number | null;
 };
+/**
+ * Supported index strategies for generated schemas.
+ */
 export declare const IndexTypes: readonly ["regular", "full_text", "vector"];
+/**
+ * Structured error payload captured alongside generated SQL.
+ */
 export type BUNSQLITEErrorObject = {
     sql?: string;
     sqlValues?: any[];
     error?: string;
 };
+/**
+ * Output of the SQL insert generator.
+ */
 export interface SQLInsertGenReturn {
     query: string;
     values: SQLInsertGenValueType[];
 }
+/**
+ * Values accepted by the SQL insert generator, including vector buffers.
+ */
 export type SQLInsertGenValueType = string | number | Float32Array<ArrayBuffer> | Buffer<ArrayBuffer>;
+/**
+ * Callback variant used when a generated insert value needs a custom
+ * placeholder.
+ */
 export type SQLInsertGenDataFn = () => {
     placeholder: string;
     value: SQLInsertGenValueType;
 };
+/**
+ * Record shape accepted by the SQL insert generator.
+ */
 export type SQLInsertGenDataType = {
     [k: string]: SQLInsertGenValueType | SQLInsertGenDataFn | undefined | null;
 };
+/**
+ * Parameters used to build a multi-row SQL insert statement.
+ */
 export type SQLInsertGenParams = {
     data: SQLInsertGenDataType[];
     tableName: string;
     dbFullName?: string;
 };
+/**
+ * Library configuration used to locate the SQLite database, schema file,
+ * generated types, and backup settings.
+ */
 export type BunSQLiteConfig = {
     db_name: string;
     /**
@@ -1015,8 +1314,14 @@ export type BunSQLiteConfig = {
      */
     typedef_file_path?: string;
 };
+/**
+ * Resolved Bun SQLite config paired with the loaded database schema.
+ */
 export type BunSQLiteConfigReturn = {
     config: BunSQLiteConfig;
     dbSchema: BUN_SQLITE_DatabaseSchemaType;
 };
+/**
+ * Default fields automatically suggested for new tables.
+ */
 export declare const DefaultFields: BUN_SQLITE_FieldSchemaType[];

dist/types/index.js

@@ -1,3 +1,7 @@
+/**
+ * User fields that should be omitted from general-purpose payloads and public
+ * responses.
+ */
 export const UsersOmitedFields = [
     "password",
     "social_id",
@@ -9,10 +13,17 @@ export const UsersOmitedFields = [
     "date_updated_code",
     "date_updated_timestamp",
 ];
+/**
+ * Supported MariaDB collations that can be applied at the database or table
+ * level.
+ */
 export const MariaDBCollations = [
     "utf8mb4_bin",
     "utf8mb4_unicode_520_ci",
 ];
+/**
+ * Supported editor/content modes for text fields.
+ */
 export const TextFieldTypesArray = [
     { title: "Plain Text", value: "plain" },
     { title: "Rich Text", value: "richText" },
@@ -25,13 +36,22 @@ export const TextFieldTypesArray = [
     { title: "Shell", value: "shell" },
     { title: "Code", value: "code" },
 ];
+/**
+ * Core SQLite column types supported by the schema builder.
+ */
 export const BUN_SQLITE_DATATYPES = [
     { value: "TEXT" },
     { value: "INTEGER" },
     { value: "BLOB" },
     { value: "REAL" },
 ];
+/**
+ * Supported logical operators for server-side query generation.
+ */
 export const ServerQueryOperators = ["AND", "OR"];
+/**
+ * Supported comparison operators for server-side query generation.
+ */
 export const ServerQueryEqualities = [
     "EQUAL",
     "LIKE",
@@ -60,6 +80,9 @@ export const ServerQueryEqualities = [
     "MATCH",
     "MATCH_BOOLEAN",
 ];
+/**
+ * Uppercase HTTP methods supported by the CRUD helpers.
+ */
 export const DataCrudRequestMethods = [
     "GET",
     "POST",
@@ -68,6 +91,10 @@ export const DataCrudRequestMethods = [
     "DELETE",
     "OPTIONS",
 ];
+/**
+ * Lowercase variant of the supported HTTP methods, used where string casing
+ * must match external APIs.
+ */
 export const DataCrudRequestMethodsLowerCase = [
     "get",
     "post",
@@ -76,7 +103,13 @@ export const DataCrudRequestMethodsLowerCase = [
     "delete",
     "options",
 ];
+/**
+ * High-level CRUD actions supported by the DSQL helpers.
+ */
 export const DsqlCrudActions = ["insert", "update", "delete", "get"];
+/**
+ * Reserved query parameter names used throughout the API layer.
+ */
 export const QueryFields = [
     "duplicate",
     "user_id",
@@ -85,6 +118,9 @@ export const QueryFields = [
     "table_id",
     "db_slug",
 ];
+/**
+ * Supported Docker Compose service names used by the deployment helpers.
+ */
 export const DockerComposeServices = [
     "setup",
     "cron",
@@ -102,7 +138,13 @@ export const DockerComposeServices = [
     "db-cron",
     "web-app-post-db-setup",
 ];
+/**
+ * Supported index strategies for generated schemas.
+ */
 export const IndexTypes = ["regular", "full_text", "vector"];
+/**
+ * Default fields automatically suggested for new tables.
+ */
 export const DefaultFields = [
     {
         fieldName: "id",

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@moduletrace/bun-sqlite",
-    "version": "1.0.23",
+    "version": "1.0.24",
     "description": "SQLite manager for Bun",
     "author": "Benjamin Toby",
     "main": "dist/index.js",

src/commands/schema.ts

@@ -7,6 +7,7 @@ import dbSchemaToTypeDef from "../lib/sqlite/schema-to-typedef";
 import _ from "lodash";
 import appendDefaultFieldsToDbSchema from "../utils/append-default-fields-to-db-schema";
 import chalk from "chalk";
+import { writeLiveSchema } from "../functions/live-schema";
 
 export default function () {
     return new Command("schema")
@@ -48,6 +49,8 @@ export default function () {
                 });
             }
 
+            writeLiveSchema({ schema: finaldbSchema });
+
             console.log(
                 `${chalk.bold(chalk.green(`DB Schema setup success!`))}`,
             );

src/data/grab-dir-names.ts

@@ -1,9 +1,23 @@
 import path from "path";
+import type { BunSQLiteConfig } from "../types";
 
-export default function grabDirNames() {
+type Params = {
+    config?: BunSQLiteConfig;
+};
+
+export default function grabDirNames(params?: Params) {
     const ROOT_DIR = process.cwd();
+    const BUN_SQLITE_DIR = path.join(ROOT_DIR, ".bun-sqlite");
+    const BUN_SQLITE_TEMP_DIR = path.join(BUN_SQLITE_DIR, ".tmp");
+    const BUN_SQLITE_LIVE_SCHEMA = path.join(
+        BUN_SQLITE_DIR,
+        "live-schema.json",
+    );
 
     return {
         ROOT_DIR,
+        BUN_SQLITE_DIR,
+        BUN_SQLITE_TEMP_DIR,
+        BUN_SQLITE_LIVE_SCHEMA,
     };
 }

src/functions/live-schema.ts

@@ -0,0 +1,24 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import grabDirNames from "../data/grab-dir-names";
+import type { BUN_SQLITE_DatabaseSchemaType } from "../types";
+import path from "path";
+
+const { BUN_SQLITE_LIVE_SCHEMA } = grabDirNames();
+
+type Params = {
+    schema: BUN_SQLITE_DatabaseSchemaType;
+};
+
+export function writeLiveSchema({ schema }: Params) {
+    mkdirSync(path.dirname(BUN_SQLITE_LIVE_SCHEMA), { recursive: true });
+    writeFileSync(BUN_SQLITE_LIVE_SCHEMA, JSON.stringify(schema));
+}
+
+export function readLiveSchema() {
+    if (!existsSync(BUN_SQLITE_LIVE_SCHEMA)) {
+        return undefined;
+    }
+
+    const live_schema = readFileSync(BUN_SQLITE_LIVE_SCHEMA, "utf-8");
+    return JSON.parse(live_schema) as BUN_SQLITE_DatabaseSchemaType;
+}

src/lib/sqlite/db-schema-manager.ts

@@ -9,6 +9,7 @@ import type {
     BUN_SQLITE_TableSchemaType,
 } from "../../types";
 import { AppData } from "../../data/app-data";
+import { readLiveSchema } from "../../functions/live-schema";
 
 // Schema Manager Class
 class SQLiteSchemaManager {
@@ -95,12 +96,32 @@ class SQLiteSchemaManager {
         existingTables: string[],
         schemaTables: string[],
     ): Promise<void> {
+        console.log(`Cleaning up tables ...`);
+
         const tablesToDrop = existingTables.filter(
             (t) =>
                 !schemaTables.includes(t) &&
                 !schemaTables.find((scT) => t.startsWith(scT + "_")),
         );
 
+        const currentSchema = readLiveSchema();
+
+        if (currentSchema?.tables?.[0]) {
+            for (let i = 0; i < currentSchema.tables.length; i++) {
+                const table = currentSchema.tables[i];
+
+                if (!table?.tableName) continue;
+
+                const does_table_exist = schemaTables.find(
+                    (t) => t == table.tableName,
+                );
+
+                if (!does_table_exist) {
+                    tablesToDrop.push(table.tableName);
+                }
+            }
+        }
+
         for (const tableName of tablesToDrop) {
             console.log(`Dropping table: ${tableName}`);
             this.db.run(`DROP TABLE IF EXISTS "${tableName}"`);