@lobb-js/core 0.18.0 → 0.20.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lobb-js/core",
   "license": "UNLICENSED",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/api/collections/collectionStore.ts

@@ -226,11 +226,15 @@ export class CollectionStore {
             transaction: client,
           },
         );
-        data = await this.dbDriver.createOne(
-          collectionName,
-          this.filterPayload(collectionName, result.data),
-          client,
-        );
+
+        if (!Lobb.instance.configManager.isCollectionVirtual(collectionName)) {
+          data = await this.dbDriver.createOne(
+            collectionName,
+            this.filterPayload(collectionName, result.data),
+            client,
+          );
+        }
+
         data = (await Lobb.instance.eventSystem.emit(
           `core.store.createOne`,
           {

package/src/api/collections/utils.ts

@@ -8,6 +8,7 @@ export function getCollectionDocumentSchema(
     const collection = Lobb.instance.configManager.getCollection(
       collectionName,
     );
+    if (collection.virtual) return z.object({}).passthrough();
     const fieldNames = Object.keys(collection.fields);
 
     const properties: Record<string, any> = {};
@@ -64,7 +65,7 @@ export function getColFieldPropSchema(
     );
   }
 
-  const requiredField = Boolean(field.validators?.required);
+  const requiredField = Boolean("validators" in field && field.validators?.required);
   if (!requiredField) {
     fieldSchema = fieldSchema.optional();
   }

package/src/api/meta/service.ts

@@ -40,6 +40,10 @@ export class MetaService {
       collections[collectionName].singleton = Lobb.instance.configManager
         .isCollectionSingleton(collectionName);
 
+      // is collection virtual
+      collections[collectionName].virtual = Lobb.instance.configManager
+        .isCollectionVirtual(collectionName);
+
       // filling the extension property
       collections[collectionName].category = collection.category;
       collections[collectionName].owner = Lobb.instance.utils
@@ -64,12 +68,15 @@ export class MetaService {
         field.label = fieldName;
         field.key = fieldName;
         field.enum = "enum" in fieldConfig ? fieldConfig.enum : undefined;
-        field.validators = fieldConfig.validators;
-        field.pre_processors = fieldConfig.pre_processors;
+        field.validators = "validators" in fieldConfig ? fieldConfig.validators : undefined;
+        field.pre_processors = "pre_processors" in fieldConfig ? fieldConfig.pre_processors : undefined;
         field.ui = fieldConfig.ui;
 
         collections[collectionName].fields[fieldName] = field;
       }
+
+      // filling the collection ui
+      collections[collectionName].ui = collection.ui;
     }
 
     return collections;

package/src/config/ConfigManager.ts

@@ -3,6 +3,7 @@ import {
   type CollectionConfig,
   CollectionConfigSchema,
   type CollectionsConfig,
+  type NormalCollectionConfig,
 } from "../types/index.ts";
 import type { CollectionField } from "../types/index.ts";
 import type { Extension } from "../types/index.ts";
@@ -47,16 +48,17 @@ export class ConfigManager {
         this.config.collections,
       )
     ) {
+      if (collectionValue.virtual) continue;
       for (
         const [fieldName, fieldValue] of Object.entries(
-          this.config.collections[collectionName].fields,
+          (this.config.collections[collectionName] as any).fields,
         )
       ) {
         if (fieldValue.type === "integer" && fieldValue.references) {
           if (!this.config.collections[fieldValue.references.collection]) {
             throw new LobbError({
               code: "INTERNAL_SERVER_ERROR",
-              message: `Field (${collectionName}.${fieldName}) references collection (${fieldValue.references.collection}) which does not exist`,
+              message: `"${collectionName}.${fieldName}" references "${fieldValue.references.collection}" which is not defined in your collections.`,
             });
           }
           if (!this.config.relations) {
@@ -82,6 +84,12 @@ export class ConfigManager {
 
     // Iterate over the collections and map each field to only include the 'type' property
     for (const collectionName in collections) {
+      // Virtual collections have no DB table — skip them entirely
+      if (collections[collectionName].virtual) {
+        delete collections[collectionName];
+        continue;
+      }
+
       // Keep only the 'indexes' and 'fields' properties in a collection
       collections[collectionName] = {
         indexes: collections[collectionName].indexes,
@@ -131,19 +139,30 @@ export class ConfigManager {
     return collection;
   }
 
+  public getNormalCollection(collectionName: string): NormalCollectionConfig {
+    const collection = this.getCollection(collectionName);
+    if (collection.virtual) {
+      throw new LobbError({
+        code: "INTERNAL_SERVER_ERROR",
+        message: `The (${collectionName}) collection is virtual and has no fields`,
+      });
+    }
+    return collection;
+  }
+
   public getFieldNames(collectionName: string) {
-    return Object.keys(
-      this.getCollection(collectionName).fields,
-    );
+    const collection = this.getCollection(collectionName);
+    if (collection.virtual) return [];
+    return Object.keys(collection.fields);
   }
 
   public fieldExists(
     fieldName: string,
     collectionName: string,
   ): boolean {
-    return Boolean(
-      this.getCollection(collectionName).fields[fieldName],
-    );
+    const collection = this.getCollection(collectionName);
+    if (collection.virtual) return false;
+    return Boolean(collection.fields[fieldName]);
   }
 
   public collectionExists(collectionName: string): boolean {
@@ -154,7 +173,8 @@ export class ConfigManager {
     fieldName: string,
     collectionName: string,
   ): CollectionField {
-    const field = this.getCollection(collectionName).fields[fieldName];
+    const collection = this.getCollection(collectionName);
+    const field = collection.virtual ? undefined : collection.fields[fieldName];
     if (!field) {
       throw new LobbError({
         code: "BAD_REQUEST",
@@ -205,7 +225,11 @@ export class ConfigManager {
     const virtualCollections: CollectionsConfig = {};
     const collections = this.getCollections();
     for (const [collectionName, collection] of Object.entries(collections)) {
-      const collectionFieldsNames = Object.keys(collection.fields);
+      if (collection.virtual) {
+        virtualCollections[collectionName] = collection;
+        continue;
+      }
+      const collectionFieldsNames = Object.keys(collection.fields ?? {});
       if (collectionFieldsNames.length <= 1) {
         virtualCollections[collectionName] = collection;
       }
@@ -253,6 +277,12 @@ export class ConfigManager {
   }
 
   public isCollectionSingleton(collectionName: string): boolean {
-    return Boolean(this.config.collections[collectionName]?.singleton);
+    const collection = this.config.collections[collectionName];
+    if (!collection || collection.virtual) return false;
+    return Boolean(collection.singleton);
+  }
+
+  public isCollectionVirtual(collectionName: string): boolean {
+    return Boolean(this.config.collections[collectionName]?.virtual);
   }
 }

package/src/config/validations.ts

@@ -37,7 +37,7 @@ function validateDBNamesAreSnakeCase(
       );
     }
     for (
-      const [fieldName, _] of Object.entries(collectionValue.fields)
+      const [fieldName, _] of Object.entries(collectionValue.virtual ? {} : collectionValue.fields)
     ) {
       if (!isSnakeCase(fieldName)) {
         throw new Error(

package/src/database/DatabaseSyncManager.ts

@@ -36,21 +36,6 @@ export class DatabaseSyncManager {
   ) {
     if (!dbSchemaDiff.length) return;
 
-    if (!forceSync) {
-      console.error(
-        "These are the differences between the config schema and the database schema",
-      );
-      console.error(
-        "You should add migrations to match the collection schema with the database schema",
-      );
-      console.error(dbSchemaDiff);
-      throw new LobbError({
-        code: "INTERNAL_SERVER_ERROR",
-        message:
-          "The schema of the configuration collection does not align with the actual schema of the connected database.",
-      });
-    }
-
     // just-diff may produce deep paths (length > 3) for sub-field changes within
     // an existing index (e.g. renaming a column the index covers). Convert those
     // into explicit drop+recreate (replace) ops, deduplicating by index name.
@@ -84,6 +69,8 @@ export class DatabaseSyncManager {
     };
     normalizedDiff.sort((a, b) => opOrder(a) - opOrder(b));
 
+    await this.assertNoDataLoss(normalizedDiff, forceSync);
+
     for (let index = 0; index < normalizedDiff.length; index++) {
       const change = normalizedDiff[index];
       if (change.path.length === 1 && change.op === "add") {
@@ -114,7 +101,7 @@ export class DatabaseSyncManager {
       } else if (change.path[1] === "fields" && change.op === "replace") {
         const collectionName = change.path[0] as string;
         const fieldName = change.path[2] as string;
-        const fieldConfig = Lobb.instance.configManager.getCollection(collectionName).fields[fieldName];
+        const fieldConfig = Lobb.instance.configManager.getNormalCollection(collectionName).fields[fieldName];
         await this.dbDriver.alterField(collectionName, fieldName, fieldConfig);
       } else if (change.path[1] === "indexes" && change.op === "add") {
         const collectionName = change.path[0] as string;
@@ -131,10 +118,10 @@ export class DatabaseSyncManager {
       } else if (change.path[1] === "indexes" && change.op === "replace") {
         const collectionName = change.path[0] as string;
         const indexName = change.path[2] as string;
-        const collectionConfig = Lobb.instance.configManager.getCollection(
+        const collectionConfig = Lobb.instance.configManager.getNormalCollection(
           collectionName,
         );
-        const indexes = collectionConfig.indexes;
+        const indexes = collectionConfig.indexes ?? {};
         const index = indexes[indexName];
         await this.dbDriver.dropIndex(collectionName, indexName);
         await this.dbDriver.createIndex(
@@ -152,6 +139,59 @@ export class DatabaseSyncManager {
     }
   }
 
+  private async assertNoDataLoss(
+    diff: Array<{ op: string; path: (string | number)[]; value: unknown }>,
+    forceSync: boolean,
+  ) {
+    if (forceSync) return;
+    const destructiveOps = diff.filter(
+      (change) =>
+        (change.path.length === 1 && change.op === "remove") ||
+        (change.path[1] === "fields" && change.op === "remove"),
+    );
+
+    if (destructiveOps.length === 0) return;
+
+    const blocked: string[] = [];
+
+    for (const change of destructiveOps) {
+      const collectionName = change.path[0] as string;
+
+      if (change.path.length === 1 && change.op === "remove") {
+        const { meta } = await this.dbDriver.findAll(collectionName, { limit: 1, offset: 0, fields: "id" });
+        if (meta.totalCount > 0) {
+          blocked.push(
+            `Table "${collectionName}" has ${meta.totalCount} row(s) and cannot be dropped automatically. Write a migration to handle the data first.`,
+          );
+        }
+      } else if (change.path[1] === "fields" && change.op === "remove") {
+        const fieldName = change.path[2] as string;
+        const { meta } = await this.dbDriver.findAll(collectionName, {
+          limit: 1,
+          offset: 0,
+          fields: "id",
+          filter: { [fieldName]: { $ne: null } },
+        });
+        if (meta.totalCount > 0) {
+          blocked.push(
+            `Column "${collectionName}.${fieldName}" has ${meta.totalCount} non-null row(s) and cannot be dropped automatically. Write a migration to handle the data first.`,
+          );
+        }
+      }
+    }
+
+    if (blocked.length > 0) {
+      console.error("Blocked destructive schema changes detected:");
+      for (const msg of blocked) console.error(` • ${msg}`);
+      throw new LobbError({
+        code: "INTERNAL_SERVER_ERROR",
+        message:
+          "Refusing to apply destructive schema changes on tables/columns that contain data. " +
+          "Write explicit migrations to handle the data, then re-run.",
+      });
+    }
+  }
+
   private async getDbDifferences(specificColleciton?: string) {
     let dbSchema = await this.dbDriver.getDbSchema();
     let configDbSchema = Lobb.instance.configManager.getDbSchema();

package/src/database/drivers/pgDriver/PGDriver.ts

@@ -1,7 +1,7 @@
 import format from "pg-format";
 import type { FindAllParamsOutput } from "../../../types/index.ts";
 import type {
-  CollectionConfig,
+  NormalCollectionConfig,
   CollectionIndex,
   CollectionIndexes,
   CollectionsConfig,
@@ -109,7 +109,7 @@ export class PGDriver extends DatabaseDriver {
 
   public async createCollection(
     collectionName: string,
-    collectionConfig: CollectionConfig,
+    collectionConfig: NormalCollectionConfig,
   ) {
     const collectionEntries = Object.entries(collectionConfig.fields);
     const createTableBodySql: string = collectionEntries.map(
@@ -127,7 +127,7 @@ export class PGDriver extends DatabaseDriver {
     await this.runQuery(client, query);
 
     // creating the indexes
-    const indexes = collectionConfig.indexes;
+    const indexes = collectionConfig.indexes ?? {};
     for (
       const [indexName, value] of Object.entries(indexes)
     ) {
@@ -423,7 +423,9 @@ export class PGDriver extends DatabaseDriver {
   }
 
   private stripVirtualFields(collectionName: string, data: any): any {
-    const fields = Lobb.instance.configManager.getCollection(collectionName).fields;
+    const collection = Lobb.instance.configManager.getCollection(collectionName);
+    if (collection.virtual) return data;
+    const fields = collection.fields;
     const result = { ...data };
     for (const key of Object.keys(result)) {
       if (fields[key]?.virtual) delete result[key];

package/src/database/drivers/pgDriver/QueryBuilder.ts

@@ -82,7 +82,7 @@ export class QueryBuilder {
     const mainFields = fields.filter((f) => !f.includes("."));
     mainFields.forEach((field) => {
       if (field === "*") {
-        const collectionFields = Lobb.instance.configManager.getCollection(this.collectionName).fields;
+        const collectionFields = Lobb.instance.configManager.getNormalCollection(this.collectionName).fields;
         const currentCollectionFields = Object.entries(collectionFields)
           .filter(([, fieldConfig]) => !fieldConfig.virtual)
           .map(([fieldName]) => fieldName);
@@ -130,7 +130,7 @@ export class QueryBuilder {
           : foreignFieldCollection;
 
         // Exclude virtual fields — they have no DB column in the related table
-        const foreignCollectionFields = Lobb.instance.configManager.getCollection(foreignFieldCollection).fields;
+        const foreignCollectionFields = Lobb.instance.configManager.getNormalCollection(foreignFieldCollection).fields;
         const nonVirtualNestedFields = nestedFields.filter((f) => !foreignCollectionFields[f]?.virtual);
 
         // Build JSON safely: only if related row exists

package/src/types/config/collectionsConfig.ts

@@ -41,15 +41,40 @@ export const CollectionFieldsSchema = z.intersection(
   z.record(CollectionFieldSchema),
 );
 
-// CollectionConfig
-export const CollectionConfigSchema = z.object({
+const CollectionTabSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  filter: z.record(z.unknown()).optional(),
+  default: z.boolean().optional(),
+});
+
+const CollectionUiSchema = z.object({
+  tabs: z.array(CollectionTabSchema).optional(),
+}).optional();
+
+// Virtual collection — no DB table, no fields, just an API endpoint for workflows to intercept
+export const VirtualCollectionConfigSchema = z.object({
+  virtual: z.literal(true),
+  category: z.string().optional(),
+  ui: CollectionUiSchema,
+});
+
+// Normal collection — has fields (required) and optional indexes
+export const NormalCollectionConfigSchema = z.object({
+  virtual: z.literal(false).optional(),
   category: z.string().optional(),
   singleton: z.boolean().optional(),
   hooks: CollectionHooksSchema,
-  indexes: CollectionIndexesSchema,
+  indexes: CollectionIndexesSchema.optional(),
   fields: CollectionFieldsSchema,
+  ui: CollectionUiSchema,
 });
 
+export const CollectionConfigSchema = z.union([
+  VirtualCollectionConfigSchema,
+  NormalCollectionConfigSchema,
+]);
+
 export const CollectionsConfigSchema = z.record(CollectionConfigSchema);
 
 // Inferred Types
@@ -59,5 +84,7 @@ export type CollectionIndex = z.infer<typeof CollectionIndexSchema>;
 export type CollectionIndexes = z.infer<typeof CollectionIndexesSchema>;
 export type CollectionFields = z.infer<typeof CollectionFieldsSchema>;
 export type CollectionFieldsWithoutId = Omit<CollectionFields, "id">;
+export type VirtualCollectionConfig = z.infer<typeof VirtualCollectionConfigSchema>;
+export type NormalCollectionConfig = z.infer<typeof NormalCollectionConfigSchema>;
 export type CollectionConfig = z.infer<typeof CollectionConfigSchema>;
 export type CollectionsConfig = z.infer<typeof CollectionsConfigSchema>;

package/src/types/index.ts

@@ -5,6 +5,7 @@ export type { Config, WebConfig } from "./config/config.ts";
 export type { RelationsConfig } from "./config/relations.ts";
 export type {
   CollectionConfig,
+  NormalCollectionConfig,
   CollectionIndex,
   CollectionIndexes,
   CollectionsConfig,

package/src/workflows/coreWorkflows/processors/defaultWorkflows.ts

@@ -2,7 +2,8 @@ import type { Workflow } from "../../WorkflowSystem.ts";
 import { Lobb } from "../../../Lobb.ts";
 
 async function applyDefaults(input: any) {
-  const fields = Lobb.instance.configManager.getCollection(input.collectionName).fields;
+  if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+  const fields = Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
   const data = input.data;
 
   for (const [fieldName, fieldConfig] of Object.entries(fields) as [string, any][]) {

package/src/workflows/coreWorkflows/processors/enumWorkflows.ts

@@ -3,7 +3,8 @@ import { Lobb } from "../../../Lobb.ts";
 import { LobbError } from "../../../LobbError.ts";
 
 async function runEnumCheck(input: any, processAllFields: boolean) {
-  const fields = Lobb.instance.configManager.getCollection(input.collectionName).fields;
+  if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+  const fields = Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
   const data = input.data;
   const errors: Record<string, string[]> = {};
 

package/src/workflows/coreWorkflows/processors/hooksWorkflows.ts

@@ -5,9 +5,10 @@ async function runFieldHooks(
   hookName: "beforeCreate" | "beforeUpdate" | "afterCreate" | "afterUpdate",
   input: any,
 ) {
-  const fields = Lobb.instance.configManager.getCollection(input.collectionName).fields;
+  if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return;
+  const fields = Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
   for (const [fieldName, fieldConfig] of Object.entries(fields)) {
-    const hook = fieldConfig.hooks?.[hookName];
+    const hook = "hooks" in fieldConfig ? fieldConfig.hooks?.[hookName] : undefined;
     if (!hook) continue;
     const result = await hook({ data: input.data, context: input.context });
     if (result !== undefined) {
@@ -21,7 +22,8 @@ export const hooksWorkflows: Workflow[] = [
     name: "core_hooksBeforeCreate",
     eventName: "core.store.preCreateOne",
     handler: async (input) => {
-      const hooks = Lobb.instance.configManager.getCollection(input.collectionName).hooks;
+      if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+      const hooks = Lobb.instance.configManager.getNormalCollection(input.collectionName).hooks;
       await hooks?.beforeCreate?.({ data: input.data, context: input.context });
       await runFieldHooks("beforeCreate", input);
       return input;
@@ -31,7 +33,8 @@ export const hooksWorkflows: Workflow[] = [
     name: "core_hooksBeforeUpdate",
     eventName: "core.store.preUpdateOne",
     handler: async (input) => {
-      const hooks = Lobb.instance.configManager.getCollection(input.collectionName).hooks;
+      if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+      const hooks = Lobb.instance.configManager.getNormalCollection(input.collectionName).hooks;
       await hooks?.beforeUpdate?.({ data: input.data, context: input.context });
       await runFieldHooks("beforeUpdate", input);
       return input;
@@ -41,7 +44,8 @@ export const hooksWorkflows: Workflow[] = [
     name: "core_hooksAfterCreate",
     eventName: "core.store.createOne",
     handler: async (input) => {
-      const hooks = Lobb.instance.configManager.getCollection(input.collectionName).hooks;
+      if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+      const hooks = Lobb.instance.configManager.getNormalCollection(input.collectionName).hooks;
       await hooks?.afterCreate?.({ data: input.data, context: input.context });
       await runFieldHooks("afterCreate", input);
       return input;
@@ -51,7 +55,8 @@ export const hooksWorkflows: Workflow[] = [
     name: "core_hooksAfterUpdate",
     eventName: "core.store.updateOne",
     handler: async (input) => {
-      const hooks = Lobb.instance.configManager.getCollection(input.collectionName).hooks;
+      if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+      const hooks = Lobb.instance.configManager.getNormalCollection(input.collectionName).hooks;
       await hooks?.afterUpdate?.({ data: input.data, context: input.context });
       await runFieldHooks("afterUpdate", input);
       return input;

package/src/workflows/coreWorkflows/processors/processors/processor.ts

@@ -9,7 +9,7 @@ export async function processor(
   processAllFields: boolean,
 ) {
   const fieldsSchema =
-    Lobb.instance.configManager.getCollection(input.collectionName).fields;
+    Lobb.instance.configManager.isCollectionVirtual(input.collectionName) ? {} as any : Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
 
   input.data = await processPayloadWithSchema(
     type,

package/src/workflows/coreWorkflows/processors/requiredWorkflows.ts

@@ -3,7 +3,8 @@ import { Lobb } from "../../../Lobb.ts";
 import { LobbError } from "../../../LobbError.ts";
 
 async function runRequiredCheck(input: any, processAllFields: boolean) {
-  const fields = Lobb.instance.configManager.getCollection(input.collectionName).fields;
+  if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+  const fields = Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
   const data = input.data;
   const errors: Record<string, string[]> = {};
 
@@ -11,7 +12,7 @@ async function runRequiredCheck(input: any, processAllFields: boolean) {
 
   for (const fieldName of fieldNames) {
     const fieldConfig = fields[fieldName];
-    if (!fieldConfig?.required) continue;
+    if (!fieldConfig || !("required" in fieldConfig) || !fieldConfig.required) continue;
 
     const value = data[fieldName];
     if (value === undefined || value === null || value === "") {

package/src/workflows/coreWorkflows/processors/validator/validator.ts

@@ -6,7 +6,7 @@ export async function validator(
   processAllFields: boolean = false,
 ) {
   const fieldsSchema =
-    Lobb.instance.configManager.getCollection(input.collectionName).fields;
+    Lobb.instance.configManager.isCollectionVirtual(input.collectionName) ? {} as any : Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
 
   await validatePayloadWithSchema(
     input.data,

package/src/workflows/coreWorkflows/processors/validatorWorkflows.ts

@@ -3,7 +3,8 @@ import { Lobb } from "../../../Lobb.ts";
 import { LobbError } from "../../../LobbError.ts";
 
 async function runFieldValidators(input: any, processAllFields: boolean) {
-  const fields = Lobb.instance.configManager.getCollection(input.collectionName).fields;
+  if (Lobb.instance.configManager.isCollectionVirtual(input.collectionName)) return input;
+  const fields = Lobb.instance.configManager.getNormalCollection(input.collectionName).fields;
   const data = input.data;
   const errors: Record<string, string[]> = {};
 
@@ -11,7 +12,7 @@ async function runFieldValidators(input: any, processAllFields: boolean) {
 
   for (const fieldName of fieldNames) {
     const fieldConfig = fields[fieldName];
-    if (!fieldConfig?.validator) continue;
+    if (!fieldConfig || !("validator" in fieldConfig) || !fieldConfig.validator) continue;
 
     const error = await fieldConfig.validator({
       value: data[fieldName],