@ronin/compiler 0.10.2 → 0.10.3-leo-ron-1083-experimental-215

package/README.md

@@ -70,6 +70,24 @@ executed and their results can be formatted by the compiler as well:
 const results: Array<Result> = transaction.prepareResults(rows);
 ```
 
+#### Root Model
+
+Before you can run any statements generated by the compiler that are altering the database schema, you need to create the table of the so-called "root model", which is used to store metadata for all other models.
+
+This table is called `ronin_schema`, which mimics the default `sqlite_schema` table provided by SQLite. You can generate its respective SQL statements like so:
+
+```typescript
+import { Transaction, ROOT_MODEL } from '@ronin/compiler';
+
+const transaction = new Transaction([
+  {
+    create: { model: ROOT_MODEL }
+  }
+]);
+```
+
+Afterward, run the statements located in `transaction.statements` to create the table for the root model. Once that is done, your database is prepared to run any statements generated by the compiler.
+
 #### Types
 
 In total, the following types are being exported:
@@ -103,7 +121,25 @@ new Transaction(queries, {
   // Instead of returning an array of parameters for every statement (which allows for
   // preventing SQL injections), all parameters are inlined directly into the SQL strings.
   // This option should only be used if the generated SQL will be manually verified.
-  inlineParams: true
+  inlineParams: true,
+
+  // By default, in the generated SQL statements, the compiler does not alias columns if
+  // multiple different tables with the same column names are being joined. Only the table
+  // names themselves are aliased.
+  //
+  // This ensures the cleanest possible SQL statements in conjunction with the default
+  // behavior of SQL databases, where the result of a statement is a list (array) of
+  // values, which are inherently not prone to conflicts.
+  //
+  // If the driver being used instead returns an object for every row, the driver must
+  // ensure the uniqueness of every key in that object, which means prefixing duplicated
+  // column names with the name of the respective table, if multiple tables are joined.
+  //
+  // Drivers that return objects for rows offer this behavior as an option that is
+  // usually called "expand columns". If the driver being used does not offer such an
+  // option, you can instead activate the option in the compiler, which results in longer
+  // SQL statements because any duplicated column name is aliased.
+  expandColumns: true
 });
 ```
 
@@ -117,7 +153,7 @@ bun run dev
 
 Whenever you make a change to the source code, it will then automatically be transpiled again.
 
-### Mental Model
+### Architecture
 
 The interface of creating new `Transaction` instances (thereby creating new transactions) was chosen in order to define the smallest workload unit that the compiler can operate on.
 

package/dist/index.d.ts

@@ -5979,7 +5979,7 @@ interface Model<T extends Array<ModelField> = Array<ModelField>> {
     triggers?: Array<ModelTrigger<T>>;
     presets?: Array<ModelPreset>;
 }
-type PublicModel<T extends Array<ModelField> = Array<ModelField>> = Omit<Partial<Model<T>>, 'slug' | 'identifiers' | 'system' | 'table' | 'tableAlias'> & {
+type PublicModel<T extends Array<ModelField> = Array<ModelField>> = Omit<Partial<Model<T>>, 'slug' | 'identifiers' | 'system' | 'tableAlias'> & {
     slug: Required<Model['slug']>;
     identifiers?: Partial<Model['identifiers']>;
 };
@@ -6005,13 +6005,22 @@ type AmountResult = {
 };
 type Result = SingleRecordResult | MultipleRecordResult | AmountResult;
 
+interface TransactionOptions {
+    /** A list of models that already exist in the database. */
+    models?: Array<PublicModel>;
+    /**
+     * Place statement parameters directly inside the statement strings instead of
+     * separating them out into a dedicated `params` array.
+     */
+    inlineParams?: boolean;
+    /** Alias column names that are duplicated when joining multiple tables. */
+    expandColumns?: boolean;
+}
 declare class Transaction {
     statements: Array<Statement>;
     models: Array<Model>;
     private queries;
-    constructor(queries: Array<Query>, options?: Parameters<typeof this.compileQueries>[2] & {
-        models?: Array<PublicModel>;
-    });
+    constructor(queries: Array<Query>, options?: TransactionOptions);
     /**
      * Composes SQL statements for the provided RONIN queries.
      *
@@ -6026,4 +6035,6 @@ declare class Transaction {
     prepareResults(results: Array<Array<Row>>): Array<Result>;
 }
 
-export { type PublicModel as Model, type ModelField, type ModelIndex, type ModelPreset, type ModelTrigger, type Query, type Result, type Statement, Transaction };
+declare const CLEAN_ROOT_MODEL: PublicModel;
+
+export { type PublicModel as Model, type ModelField, type ModelIndex, type ModelPreset, type ModelTrigger, type Query, CLEAN_ROOT_MODEL as ROOT_MODEL, type Result, type Statement, Transaction };

package/dist/index.js

@@ -65,6 +65,23 @@ var convertToCamelCase = (str) => {
   return sanitize(str).split(SPLIT_REGEX).map((part, index) => index === 0 ? part.toLowerCase() : capitalize(part)).join("");
 };
 var isObject = (value) => value != null && typeof value === "object" && Array.isArray(value) === false;
+var getSymbol = (value) => {
+  if (!isObject(value)) return null;
+  const objectValue = value;
+  if (RONIN_MODEL_SYMBOLS.QUERY in objectValue) {
+    return {
+      type: "query",
+      value: objectValue[RONIN_MODEL_SYMBOLS.QUERY]
+    };
+  }
+  if (RONIN_MODEL_SYMBOLS.EXPRESSION in objectValue) {
+    return {
+      type: "expression",
+      value: objectValue[RONIN_MODEL_SYMBOLS.EXPRESSION]
+    };
+  }
+  return null;
+};
 var findInObject = (obj, pattern, replacer) => {
   let found = false;
   for (const key in obj) {
@@ -85,14 +102,18 @@ var findInObject = (obj, pattern, replacer) => {
 var flatten = (obj, prefix = "", res = {}) => {
   for (const key in obj) {
     const path = prefix ? `${prefix}.${key}` : key;
-    if (typeof obj[key] === "object" && obj[key] !== null) {
-      flatten(obj[key], path, res);
+    const value = obj[key];
+    if (typeof value === "object" && value !== null && !getSymbol(value)) {
+      flatten(value, path, res);
     } else {
-      res[path] = obj[key];
+      res[path] = value;
     }
   }
   return res;
 };
+var omit = (obj, properties) => Object.fromEntries(
+  Object.entries(obj).filter(([key]) => !properties.includes(key))
+);
 var expand = (obj) => {
   return Object.entries(obj).reduce((res, [key, val]) => {
     key.split(".").reduce((acc, part, i, arr) => {
@@ -275,23 +296,6 @@ var formatIdentifiers = ({ identifiers }, queryInstructions) => {
     [type]: newNestedInstructions
   };
 };
-var getSymbol = (value) => {
-  if (!isObject(value)) return null;
-  const objectValue = value;
-  if (RONIN_MODEL_SYMBOLS.QUERY in objectValue) {
-    return {
-      type: "query",
-      value: objectValue[RONIN_MODEL_SYMBOLS.QUERY]
-    };
-  }
-  if (RONIN_MODEL_SYMBOLS.EXPRESSION in objectValue) {
-    return {
-      type: "expression",
-      value: objectValue[RONIN_MODEL_SYMBOLS.EXPRESSION]
-    };
-  }
-  return null;
-};
 
 // src/instructions/with.ts
 var getMatcher = (value, negative) => {
@@ -693,7 +697,7 @@ var transformMetaQuery = (models, dependencyStatements, statementParams, query)
   if (!(modelSlug && slug)) return query;
   const model = action === "create" && entity === "model" ? null : getModelBySlug(models, modelSlug);
   if (entity === "model") {
-    let queryTypeDetails;
+    let queryTypeDetails = {};
     if (action === "create") {
       const newModel = jsonValue;
       const modelWithFields = addDefaultModelFields(newModel, true);
@@ -749,6 +753,8 @@ var transformMetaQuery = (models, dependencyStatements, statementParams, query)
         return handleSystemModel(models, dependencyStatements, "drop", systemModel);
       });
     }
+    const modelSlug2 = "to" in queryTypeDetails ? queryTypeDetails?.to?.slug : "with" in queryTypeDetails ? queryTypeDetails?.with?.slug : void 0;
+    if (modelSlug2 === "model") return null;
     const queryTypeAction = action === "create" ? "add" : action === "alter" ? "set" : "remove";
     return {
       [queryTypeAction]: {
@@ -1178,32 +1184,44 @@ var handleOrderedBy = (model, instruction) => {
 };
 
 // src/instructions/selecting.ts
-var handleSelecting = (model, statementParams, instructions) => {
+var handleSelecting = (models, model, statementParams, instructions, options) => {
   let isJoining = false;
   let statement = instructions.selecting ? instructions.selecting.map((slug) => {
     return getFieldFromModel(model, slug, "selecting").fieldSelector;
   }).join(", ") : "*";
   if (instructions.including) {
-    const filteredObject = Object.entries(instructions.including).map(([key, value]) => {
+    const filteredObject = Object.entries(instructions.including).flatMap(([key, value]) => {
       const symbol = getSymbol(value);
-      if (symbol) {
-        if (symbol.type === "query") {
-          isJoining = true;
-          return null;
-        }
-        if (symbol.type === "expression") {
-          value = parseFieldExpression(model, "including", symbol.value);
-        }
+      if (symbol?.type === "query") {
+        isJoining = true;
+        if (!options?.expandColumns) return null;
+        const { queryModel: queryModelSlug } = splitQuery(symbol.value);
+        const queryModel = getModelBySlug(models, queryModelSlug);
+        const tableName = `including_${key}`;
+        const duplicatedFields = queryModel.fields.filter((field) => {
+          if (field.type === "group") return null;
+          return model.fields.some((modelField) => modelField.slug === field.slug);
+        }).filter((item) => item !== null);
+        return duplicatedFields.map((field) => ({
+          key: `${tableName}.${field.slug}`,
+          value: {
+            [RONIN_MODEL_SYMBOLS.EXPRESSION]: `${RONIN_MODEL_SYMBOLS.FIELD}${field.slug}`
+          }
+        }));
       }
-      return [key, value];
-    }).filter((entry) => entry !== null);
+      return { key, value };
+    }).filter((entry) => entry !== null).map((entry) => [entry.key, entry.value]);
     const newObjectEntries = Object.entries(flatten(Object.fromEntries(filteredObject)));
     if (newObjectEntries.length > 0) {
       statement += ", ";
       statement += newObjectEntries.map(([key, value]) => {
-        if (typeof value === "string" && value.startsWith('"'))
-          return `(${value}) as "${key}"`;
-        return `${prepareStatementValue(statementParams, value)} as "${key}"`;
+        const symbol = getSymbol(value);
+        if (symbol?.type === "expression") {
+          value = `(${parseFieldExpression(model, "including", symbol.value)})`;
+        } else {
+          value = prepareStatementValue(statementParams, value);
+        }
+        return `${value} as "${key}"`;
       }).join(", ");
     }
   }
@@ -1340,6 +1358,7 @@ var compileQueryInput = (defaultQuery, models, statementParams, options) => {
     statementParams,
     defaultQuery
   );
+  if (query === null) return { dependencies: [], main: dependencyStatements[0] };
   const parsedQuery = splitQuery(query);
   const { queryType, queryModel, queryInstructions } = parsedQuery;
   const model = getModelBySlug(models, queryModel);
@@ -1349,10 +1368,16 @@ var compileQueryInput = (defaultQuery, models, statementParams, options) => {
   if (instructions && Object.hasOwn(instructions, "for")) {
     instructions = handleFor(model, instructions);
   }
-  const { columns, isJoining } = handleSelecting(model, statementParams, {
-    selecting: instructions?.selecting,
-    including: instructions?.including
-  });
+  const { columns, isJoining } = handleSelecting(
+    models,
+    model,
+    statementParams,
+    {
+      selecting: instructions?.selecting,
+      including: instructions?.including
+    },
+    options
+  );
   let statement = "";
   switch (queryType) {
     case "get":
@@ -1512,7 +1537,8 @@ var Transaction = class {
       const result = compileQueryInput(
         query,
         modelListWithPresets,
-        options?.inlineParams ? null : []
+        options?.inlineParams ? null : [],
+        { expandColumns: options?.expandColumns }
       );
       dependencyStatements.push(...result.dependencies);
       mainStatements.push(result.main);
@@ -1577,6 +1603,8 @@ var Transaction = class {
     });
   }
 };
+var CLEAN_ROOT_MODEL = omit(ROOT_MODEL, ["system"]);
 export {
+  CLEAN_ROOT_MODEL as ROOT_MODEL,
   Transaction
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronin/compiler",
-  "version": "0.10.2",
+  "version": "0.10.3-leo-ron-1083-experimental-215",
   "type": "module",
   "description": "Compiles RONIN queries to SQL statements.",
   "publishConfig": {