@ronin/compiler 0.10.3 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # RONIN Compiler
 
-This package compiles [RONIN queries](https://ronin.co/docs/queries) to SQL statements.
+This package compiles [RONIN queries](https://ronin.co/docs/queries) to [SQLite](https://www.sqlite.org) statements.
 
 ## Setup
 
@@ -65,9 +65,11 @@ Once the RONIN queries have been compiled down to SQL statements, the statements
 executed and their results can be formatted by the compiler as well:
 
 ```typescript
-// `rows` are provided by the database engine
+// Passing `rawResults` (rows being of arrays of values) provided by the database (ideal)
+const results: Array<Result> = transaction.formatResults(rawResults);
 
-const results: Array<Result> = transaction.prepareResults(rows);
+// Passing `objectResults` (rows being of objects) provided by a driver
+const results: Array<Result> = transaction.formatResults(objectResults, false);
 ```
 
 #### Root Model
@@ -133,12 +135,13 @@ new Transaction(queries, {
   //
   // 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.
+  // column names with the name of the respective table, if multiple tables are joined
+  // (example for an object key: "table_name.column_name").
   //
   // 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.
+  // SQL statements because all column names are aliased.
   expandColumns: true
 });
 ```

package/dist/index.d.ts

@@ -5867,7 +5867,7 @@ type ModelFieldBasics = {
     increment?: boolean;
 };
 type ModelFieldNormal = ModelFieldBasics & {
-    type: 'string' | 'number' | 'boolean' | 'date' | 'json' | 'group';
+    type: 'string' | 'number' | 'boolean' | 'date' | 'json';
 };
 type ModelFieldReferenceAction = 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'SET DEFAULT' | 'NO ACTION';
 type ModelFieldReference = ModelFieldBasics & {
@@ -5984,7 +5984,8 @@ type PublicModel<T extends Array<ModelField> = Array<ModelField>> = Omit<Partial
     identifiers?: Partial<Model['identifiers']>;
 };
 
-type Row = Record<string, unknown>;
+type RawRow = Array<unknown>;
+type ObjectRow = Record<string, unknown>;
 type NativeRecord = Record<string, unknown> & {
     id: string;
     ronin: {
@@ -6005,6 +6006,45 @@ type AmountResult = {
 };
 type Result = SingleRecordResult | MultipleRecordResult | AmountResult;
 
+/**
+ * A list of placeholders that can be located inside queries after those queries were
+ * serialized into JSON objects.
+ *
+ * These placeholders are used to represent special keys and values. For example, if a
+ * query is nested into a query, the nested query will be marked with `__RONIN_QUERY`,
+ * which allows for distinguishing that nested query from an object of instructions.
+ */
+declare const QUERY_SYMBOLS: {
+    readonly QUERY: "__RONIN_QUERY";
+    readonly EXPRESSION: "__RONIN_EXPRESSION";
+    readonly FIELD: "__RONIN_FIELD_";
+    readonly FIELD_PARENT: "__RONIN_FIELD_PARENT_";
+    readonly FIELD_PARENT_OLD: "__RONIN_FIELD_PARENT_OLD_";
+    readonly FIELD_PARENT_NEW: "__RONIN_FIELD_PARENT_NEW_";
+    readonly VALUE: "__RONIN_VALUE";
+};
+type RoninErrorCode = 'MODEL_NOT_FOUND' | 'FIELD_NOT_FOUND' | 'INDEX_NOT_FOUND' | 'TRIGGER_NOT_FOUND' | 'PRESET_NOT_FOUND' | 'INVALID_WITH_VALUE' | 'INVALID_TO_VALUE' | 'INVALID_INCLUDING_VALUE' | 'INVALID_FOR_VALUE' | 'INVALID_BEFORE_OR_AFTER_INSTRUCTION' | 'INVALID_MODEL_VALUE' | 'MUTUALLY_EXCLUSIVE_INSTRUCTIONS' | 'MISSING_INSTRUCTION' | 'MISSING_FIELD';
+interface Issue {
+    message: string;
+    path: Array<string | number>;
+}
+interface Details {
+    message: string;
+    code: RoninErrorCode;
+    field?: string;
+    fields?: Array<string>;
+    issues?: Array<Issue>;
+    queries?: Array<Query> | null;
+}
+declare class RoninError extends Error {
+    code: Details['code'];
+    field?: Details['field'];
+    fields?: Details['fields'];
+    issues?: Details['issues'];
+    queries?: Details['queries'];
+    constructor(details: Details);
+}
+
 interface TransactionOptions {
     /** A list of models that already exist in the database. */
     models?: Array<PublicModel>;
@@ -6020,6 +6060,7 @@ declare class Transaction {
     statements: Array<Statement>;
     models: Array<Model>;
     private queries;
+    private fields;
     constructor(queries: Array<Query>, options?: TransactionOptions);
     /**
      * Composes SQL statements for the provided RONIN queries.
@@ -6031,10 +6072,11 @@ declare class Transaction {
      * @returns The composed SQL statements.
      */
     private compileQueries;
-    private formatRecord;
-    prepareResults(results: Array<Array<Row>>): Array<Result>;
+    private formatRow;
+    formatResults(results: Array<Array<RawRow>>, raw?: true): Array<Result>;
+    formatResults(results: Array<Array<ObjectRow>>, raw?: false): Array<Result>;
 }
 
 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 };
+export { type PublicModel as Model, type ModelField, type ModelIndex, type ModelPreset, type ModelTrigger, QUERY_SYMBOLS, type Query, CLEAN_ROOT_MODEL as ROOT_MODEL, type Result, RoninError, type Statement, Transaction };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/utils/helpers.ts
 import { init as cuid } from "@paralleldrive/cuid2";
-var RONIN_MODEL_SYMBOLS = {
+var QUERY_SYMBOLS = {
   // Represents a sub query.
   QUERY: "__RONIN_QUERY",
   // Represents an expression that should be evaluated.
@@ -17,9 +17,10 @@ var RONIN_MODEL_SYMBOLS = {
   VALUE: "__RONIN_VALUE"
 };
 var RONIN_MODEL_FIELD_REGEX = new RegExp(
-  `${RONIN_MODEL_SYMBOLS.FIELD}[_a-zA-Z0-9]+`,
+  `${QUERY_SYMBOLS.FIELD}[_a-zA-Z0-9.]+`,
   "g"
 );
+var composeIncludedTableAlias = (fieldSlug) => `including_${fieldSlug}`;
 var MODEL_ENTITY_ERROR_CODES = {
   field: "FIELD_NOT_FOUND",
   index: "INDEX_NOT_FOUND",
@@ -65,6 +66,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 (QUERY_SYMBOLS.QUERY in objectValue) {
+    return {
+      type: "query",
+      value: objectValue[QUERY_SYMBOLS.QUERY]
+    };
+  }
+  if (QUERY_SYMBOLS.EXPRESSION in objectValue) {
+    return {
+      type: "expression",
+      value: objectValue[QUERY_SYMBOLS.EXPRESSION]
+    };
+  }
+  return null;
+};
 var findInObject = (obj, pattern, replacer) => {
   let found = false;
   for (const key in obj) {
@@ -85,10 +103,11 @@ 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;
@@ -99,7 +118,11 @@ var omit = (obj, properties) => Object.fromEntries(
 var expand = (obj) => {
   return Object.entries(obj).reduce((res, [key, val]) => {
     key.split(".").reduce((acc, part, i, arr) => {
-      acc[part] = i === arr.length - 1 ? val : acc[part] || {};
+      if (i === arr.length - 1) {
+        acc[part] = val;
+      } else {
+        acc[part] = typeof acc[part] === "object" && acc[part] !== null ? acc[part] : {};
+      }
       return acc[part];
     }, res);
     return res;
@@ -133,15 +156,15 @@ var prepareStatementValue = (statementParams, value) => {
 };
 var parseFieldExpression = (model, instructionName, expression, parentModel) => {
   return expression.replace(RONIN_MODEL_FIELD_REGEX, (match) => {
-    let toReplace = RONIN_MODEL_SYMBOLS.FIELD;
+    let toReplace = QUERY_SYMBOLS.FIELD;
     let rootModel = model;
-    if (match.startsWith(RONIN_MODEL_SYMBOLS.FIELD_PARENT)) {
+    if (match.startsWith(QUERY_SYMBOLS.FIELD_PARENT)) {
       rootModel = parentModel;
-      toReplace = RONIN_MODEL_SYMBOLS.FIELD_PARENT;
-      if (match.startsWith(RONIN_MODEL_SYMBOLS.FIELD_PARENT_OLD)) {
-        rootModel.tableAlias = toReplace = RONIN_MODEL_SYMBOLS.FIELD_PARENT_OLD;
-      } else if (match.startsWith(RONIN_MODEL_SYMBOLS.FIELD_PARENT_NEW)) {
-        rootModel.tableAlias = toReplace = RONIN_MODEL_SYMBOLS.FIELD_PARENT_NEW;
+      toReplace = QUERY_SYMBOLS.FIELD_PARENT;
+      if (match.startsWith(QUERY_SYMBOLS.FIELD_PARENT_OLD)) {
+        rootModel.tableAlias = toReplace = QUERY_SYMBOLS.FIELD_PARENT_OLD;
+      } else if (match.startsWith(QUERY_SYMBOLS.FIELD_PARENT_NEW)) {
+        rootModel.tableAlias = toReplace = QUERY_SYMBOLS.FIELD_PARENT_NEW;
       }
     }
     const fieldSlug = match.replace(toReplace, "");
@@ -190,47 +213,52 @@ var composeConditions = (models, model, statementParams, instructionName, value,
     return conditions.join(" AND ");
   }
   if (options.fieldSlug) {
-    const fieldDetails = getFieldFromModel(model, options.fieldSlug, instructionName);
-    const { field: modelField } = fieldDetails;
-    const consumeJSON = modelField.type === "json" && instructionName === "to";
-    if (!(isObject(value) || Array.isArray(value)) || getSymbol(value) || consumeJSON) {
-      return composeFieldValues(
-        models,
-        model,
-        statementParams,
-        instructionName,
-        value,
-        { ...options, fieldSlug: options.fieldSlug }
-      );
-    }
-    if (modelField.type === "link" && isNested) {
-      const keys = Object.keys(value);
-      const values = Object.values(value);
-      let recordTarget;
-      if (keys.length === 1 && keys[0] === "id") {
-        recordTarget = values[0];
-      } else {
-        const relatedModel = getModelBySlug(models, modelField.target);
-        const subQuery = {
-          get: {
-            [relatedModel.slug]: {
-              with: value,
-              selecting: ["id"]
+    const childField = model.fields.some(({ slug }) => {
+      return slug.includes(".") && slug.split(".")[0] === options.fieldSlug;
+    });
+    if (!childField) {
+      const fieldDetails = getFieldFromModel(model, options.fieldSlug, instructionName);
+      const { field: modelField } = fieldDetails || {};
+      const consumeJSON = modelField?.type === "json" && instructionName === "to";
+      if (modelField && !(isObject(value) || Array.isArray(value)) || getSymbol(value) || consumeJSON) {
+        return composeFieldValues(
+          models,
+          model,
+          statementParams,
+          instructionName,
+          value,
+          { ...options, fieldSlug: options.fieldSlug }
+        );
+      }
+      if (modelField?.type === "link" && isNested) {
+        const keys = Object.keys(value);
+        const values = Object.values(value);
+        let recordTarget;
+        if (keys.length === 1 && keys[0] === "id") {
+          recordTarget = values[0];
+        } else {
+          const relatedModel = getModelBySlug(models, modelField.target);
+          const subQuery = {
+            get: {
+              [relatedModel.slug]: {
+                with: value,
+                selecting: ["id"]
+              }
             }
-          }
-        };
-        recordTarget = {
-          [RONIN_MODEL_SYMBOLS.QUERY]: subQuery
-        };
+          };
+          recordTarget = {
+            [QUERY_SYMBOLS.QUERY]: subQuery
+          };
+        }
+        return composeConditions(
+          models,
+          model,
+          statementParams,
+          instructionName,
+          recordTarget,
+          options
+        );
       }
-      return composeConditions(
-        models,
-        model,
-        statementParams,
-        instructionName,
-        recordTarget,
-        options
-      );
     }
   }
   if (isNested) {
@@ -278,23 +306,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) => {
@@ -347,7 +358,7 @@ var getModelBySlug = (models, slug) => {
 };
 var composeAssociationModelSlug = (model, field) => convertToCamelCase(`ronin_link_${model.slug}_${field.slug}`);
 var getFieldSelector = (model, field, fieldPath, instructionName) => {
-  const symbol = model.tableAlias?.startsWith(RONIN_MODEL_SYMBOLS.FIELD_PARENT) ? `${model.tableAlias.replace(RONIN_MODEL_SYMBOLS.FIELD_PARENT, "").slice(0, -1)}.` : "";
+  const symbol = model.tableAlias?.startsWith(QUERY_SYMBOLS.FIELD_PARENT) ? `${model.tableAlias.replace(QUERY_SYMBOLS.FIELD_PARENT, "").slice(0, -1)}.` : "";
   const tablePrefix = symbol || (model.tableAlias ? `"${model.tableAlias}".` : "");
   if (field.type === "json" && instructionName !== "to") {
     const dotParts = fieldPath.split(".");
@@ -357,7 +368,7 @@ var getFieldSelector = (model, field, fieldPath, instructionName) => {
   }
   return `${tablePrefix}"${fieldPath}"`;
 };
-var getFieldFromModel = (model, fieldPath, instructionName) => {
+function getFieldFromModel(model, fieldPath, instructionName, shouldThrow = true) {
   const errorPrefix = `Field "${fieldPath}" defined for \`${instructionName}\``;
   const modelFields = model.fields || [];
   let modelField;
@@ -375,16 +386,19 @@ var getFieldFromModel = (model, fieldPath, instructionName) => {
   }
   modelField = modelFields.find((field) => field.slug === fieldPath);
   if (!modelField) {
-    throw new RoninError({
-      message: `${errorPrefix} does not exist in model "${model.name}".`,
-      code: "FIELD_NOT_FOUND",
-      field: fieldPath,
-      queries: null
-    });
+    if (shouldThrow) {
+      throw new RoninError({
+        message: `${errorPrefix} does not exist in model "${model.name}".`,
+        code: "FIELD_NOT_FOUND",
+        field: fieldPath,
+        queries: null
+      });
+    }
+    return null;
   }
   const fieldSelector = getFieldSelector(model, modelField, fieldPath, instructionName);
   return { field: modelField, fieldSelector };
-};
+}
 var slugToName = (slug) => {
   const name = slug.replace(/([a-z])([A-Z])/g, "$1 $2");
   return title(name);
@@ -440,11 +454,6 @@ var SYSTEM_FIELDS = [
     slug: "id",
     displayAs: "single-line"
   },
-  {
-    name: "RONIN",
-    type: "group",
-    slug: "ronin"
-  },
   {
     name: "RONIN - Locked",
     type: "boolean",
@@ -488,7 +497,6 @@ var ROOT_MODEL = {
     { slug: "pluralSlug", type: "string" },
     { slug: "idPrefix", type: "string" },
     { slug: "table", type: "string" },
-    { slug: "identifiers", type: "group" },
     { slug: "identifiers.name", type: "string" },
     { slug: "identifiers.slug", type: "string" },
     // Providing an empty object as a default value allows us to use `json_insert`
@@ -543,14 +551,14 @@ var addDefaultModelPresets = (list, model) => {
         instructions: {
           including: {
             [field.slug]: {
-              [RONIN_MODEL_SYMBOLS.QUERY]: {
+              [QUERY_SYMBOLS.QUERY]: {
                 get: {
                   [relatedModel.slug]: {
                     with: {
                       // Compare the `id` field of the related model to the link field on
                       // the root model (`field.slug`).
                       id: {
-                        [RONIN_MODEL_SYMBOLS.EXPRESSION]: `${RONIN_MODEL_SYMBOLS.FIELD_PARENT}${field.slug}`
+                        [QUERY_SYMBOLS.EXPRESSION]: `${QUERY_SYMBOLS.FIELD_PARENT}${field.slug}`
                       }
                     }
                   }
@@ -578,12 +586,12 @@ var addDefaultModelPresets = (list, model) => {
       instructions: {
         including: {
           [presetSlug]: {
-            [RONIN_MODEL_SYMBOLS.QUERY]: {
+            [QUERY_SYMBOLS.QUERY]: {
               get: {
                 [pluralSlug]: {
                   with: {
                     [childField.slug]: {
-                      [RONIN_MODEL_SYMBOLS.EXPRESSION]: `${RONIN_MODEL_SYMBOLS.FIELD_PARENT}id`
+                      [QUERY_SYMBOLS.EXPRESSION]: `${QUERY_SYMBOLS.FIELD_PARENT}id`
                     }
                   }
                 }
@@ -610,7 +618,6 @@ var typesInSQLite = {
   json: "TEXT"
 };
 var getFieldStatement = (models, model, field) => {
-  if (field.type === "group") return null;
   let statement = `"${field.slug}" ${typesInSQLite[field.type]}`;
   if (field.slug === "id") statement += " PRIMARY KEY";
   if (field.unique === true) statement += " UNIQUE";
@@ -850,11 +857,11 @@ var transformMetaQuery = (models, dependencyStatements, statementParams, query)
         statementParts.push(`OF (${fieldSelectors.join(", ")})`);
       }
       statementParts.push("ON", `"${existingModel.table}"`);
-      if (trigger.filter || trigger.effects.some((query2) => findInObject(query2, RONIN_MODEL_SYMBOLS.FIELD))) {
+      if (trigger.filter || trigger.effects.some((query2) => findInObject(query2, QUERY_SYMBOLS.FIELD))) {
         statementParts.push("FOR EACH ROW");
       }
       if (trigger.filter) {
-        const tableAlias = trigger.action === "DELETE" ? RONIN_MODEL_SYMBOLS.FIELD_PARENT_OLD : RONIN_MODEL_SYMBOLS.FIELD_PARENT_NEW;
+        const tableAlias = trigger.action === "DELETE" ? QUERY_SYMBOLS.FIELD_PARENT_OLD : QUERY_SYMBOLS.FIELD_PARENT_NEW;
         const withStatement = handleWith(
           models,
           { ...existingModel, tableAlias },
@@ -876,7 +883,7 @@ var transformMetaQuery = (models, dependencyStatements, statementParams, query)
     }
     dependencyStatements.push({ statement, params });
   }
-  const field = `${RONIN_MODEL_SYMBOLS.FIELD}${pluralType}`;
+  const field = `${QUERY_SYMBOLS.FIELD}${pluralType}`;
   let json;
   switch (action) {
     case "create": {
@@ -940,7 +947,7 @@ var transformMetaQuery = (models, dependencyStatements, statementParams, query)
       model: {
         with: { slug: modelSlug },
         to: {
-          [pluralType]: { [RONIN_MODEL_SYMBOLS.EXPRESSION]: json }
+          [pluralType]: { [QUERY_SYMBOLS.EXPRESSION]: json }
         }
       }
     }
@@ -1059,8 +1066,8 @@ var handleFor = (model, instructions) => {
     if (arg !== null) {
       findInObject(
         replacedForFilter,
-        RONIN_MODEL_SYMBOLS.VALUE,
-        (match) => match.replace(RONIN_MODEL_SYMBOLS.VALUE, arg)
+        QUERY_SYMBOLS.VALUE,
+        (match) => match.replace(QUERY_SYMBOLS.VALUE, arg)
       );
     }
     for (const subInstruction in replacedForFilter) {
@@ -1102,7 +1109,7 @@ var handleIncluding = (models, model, statementParams, instruction) => {
     const relatedModel = getModelBySlug(models, queryModel);
     let joinType = "LEFT";
     let relatedTableSelector = `"${relatedModel.table}"`;
-    const tableAlias = `including_${ephemeralFieldSlug}`;
+    const tableAlias = composeIncludedTableAlias(ephemeralFieldSlug);
     const single = queryModel !== relatedModel.pluralSlug;
     if (!modifiableQueryInstructions?.with) {
       joinType = "CROSS";
@@ -1183,36 +1190,70 @@ var handleOrderedBy = (model, instruction) => {
 };
 
 // src/instructions/selecting.ts
-var handleSelecting = (model, statementParams, instructions) => {
+var handleSelecting = (models, model, statementParams, instructions, options) => {
+  let loadedFields = [];
+  let statement = "*";
   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 flatObject = flatten(instructions.including);
+    instructions.including = {};
+    for (const [key, value] of Object.entries(flatObject)) {
       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;
+        const { queryModel, queryInstructions } = splitQuery(symbol.value);
+        const subQueryModel = getModelBySlug(models, queryModel);
+        const tableName = composeIncludedTableAlias(key);
+        const queryModelFields = queryInstructions?.selecting ? subQueryModel.fields.filter((field) => {
+          return queryInstructions.selecting?.includes(field.slug);
+        }) : subQueryModel.fields;
+        for (const field of queryModelFields) {
+          loadedFields.push({ ...field, parentField: key });
+          if (options?.expandColumns) {
+            const newValue2 = parseFieldExpression(
+              { ...subQueryModel, tableAlias: tableName },
+              "including",
+              `${QUERY_SYMBOLS.FIELD}${field.slug}`
+            );
+            instructions.including[`${tableName}.${field.slug}`] = newValue2;
+          }
         }
+        continue;
       }
-      return [key, value];
-    }).filter((entry) => entry !== null);
-    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}"`;
-      }).join(", ");
+      let newValue = value;
+      if (symbol?.type === "expression") {
+        newValue = `(${parseFieldExpression(model, "including", symbol.value)})`;
+      } else {
+        newValue = prepareStatementValue(statementParams, value);
+      }
+      instructions.including[key] = newValue;
     }
   }
-  return { columns: statement, isJoining };
+  const expandColumns = isJoining && options?.expandColumns;
+  if (expandColumns) {
+    instructions.selecting = model.fields.map((field) => field.slug);
+  }
+  if (instructions.selecting) {
+    const usableModel = expandColumns ? { ...model, tableAlias: model.tableAlias || model.table } : model;
+    const selectedFields = [];
+    statement = instructions.selecting.map((slug) => {
+      const { field, fieldSelector } = getFieldFromModel(
+        usableModel,
+        slug,
+        "selecting"
+      );
+      selectedFields.push(field);
+      return fieldSelector;
+    }).join(", ");
+    loadedFields = [...selectedFields, ...loadedFields];
+  } else {
+    loadedFields = [...model.fields, ...loadedFields];
+  }
+  if (instructions.including && Object.keys(instructions.including).length > 0) {
+    statement += ", ";
+    statement += Object.entries(instructions.including).map(([key, value]) => `${value} as "${key}"`).join(", ");
+  }
+  return { columns: statement, isJoining, loadedFields };
 };
 
 // src/instructions/to.ts
@@ -1279,8 +1320,8 @@ var handleTo = (models, model, statementParams, queryType, dependencyStatements,
   Object.assign(toInstruction, defaultFields);
   for (const fieldSlug in toInstruction) {
     const fieldValue = toInstruction[fieldSlug];
-    const fieldDetails = getFieldFromModel(model, fieldSlug, "to");
-    if (fieldDetails.field.type === "link" && fieldDetails.field.kind === "many") {
+    const fieldDetails = getFieldFromModel(model, fieldSlug, "to", false);
+    if (fieldDetails?.field.type === "link" && fieldDetails.field.kind === "many") {
       delete toInstruction[fieldSlug];
       const associativeModelSlug = composeAssociationModelSlug(model, fieldDetails.field);
       const composeStatement = (subQueryType, value) => {
@@ -1345,7 +1386,8 @@ var compileQueryInput = (defaultQuery, models, statementParams, options) => {
     statementParams,
     defaultQuery
   );
-  if (query === null) return { dependencies: [], main: dependencyStatements[0] };
+  if (query === null)
+    return { dependencies: [], main: dependencyStatements[0], loadedFields: [] };
   const parsedQuery = splitQuery(query);
   const { queryType, queryModel, queryInstructions } = parsedQuery;
   const model = getModelBySlug(models, queryModel);
@@ -1355,10 +1397,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, loadedFields } = handleSelecting(
+    models,
+    model,
+    statementParams,
+    {
+      selecting: instructions?.selecting,
+      including: instructions?.including
+    },
+    options
+  );
   let statement = "";
   switch (queryType) {
     case "get":
@@ -1478,7 +1526,8 @@ var compileQueryInput = (defaultQuery, models, statementParams, options) => {
   if (returning) mainStatement.returning = true;
   return {
     dependencies: dependencyStatements,
-    main: mainStatement
+    main: mainStatement,
+    loadedFields
   };
 };
 
@@ -1487,6 +1536,7 @@ var Transaction = class {
   statements;
   models = [];
   queries;
+  fields = [];
   constructor(queries, options) {
     const models = options?.models || [];
     this.statements = this.compileQueries(queries, models, options);
@@ -1518,46 +1568,72 @@ 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);
+      this.fields.push(result.loadedFields);
     }
     this.models = modelListWithPresets;
     return [...dependencyStatements, ...mainStatements];
   };
-  formatRecord(model, record) {
-    const formattedRecord = { ...record };
-    for (const key in record) {
-      const { field } = getFieldFromModel(model, key, "to");
+  formatRow(fields, row) {
+    const record = {};
+    for (let index = 0; index < row.length; index++) {
+      const value = row[index];
+      const field = fields[index];
+      let newSlug = field.slug;
+      let newValue = value;
+      const parentFieldSlug = field.parentField;
+      if (parentFieldSlug) {
+        newSlug = `${parentFieldSlug}.${field.slug}`;
+      }
       if (field.type === "json") {
-        formattedRecord[key] = JSON.parse(record[key]);
-        continue;
+        newValue = JSON.parse(value);
       }
-      formattedRecord[key] = record[key];
+      record[newSlug] = newValue;
     }
-    return expand(formattedRecord);
+    return expand(record);
   }
-  prepareResults(results) {
+  /**
+   * Format the results returned from the database into RONIN records.
+   *
+   * @param results - A list of results from the database, where each result is an array
+   * of rows.
+   * @param raw - By default, rows are expected to be arrays of values, which is how SQL
+   * databases return rows by default. If the driver being used returns rows as objects
+   * instead, this option should be set to `false`.
+   *
+   * @returns A list of formatted RONIN results, where each result is either a single
+   * RONIN record, an array of RONIN records, or a RONIN count result.
+   */
+  formatResults(results, raw = true) {
     const relevantResults = results.filter((_, index) => {
       return this.statements[index].returning;
     });
-    return relevantResults.map((result, index) => {
+    const normalizedResults = raw ? relevantResults : relevantResults.map((rows) => {
+      return rows.map((row) => {
+        if (Array.isArray(row)) return row;
+        if (row["COUNT(*)"]) return [row["COUNT(*)"]];
+        return Object.values(row);
+      });
+    });
+    return normalizedResults.map((rows, index) => {
       const query = this.queries.at(-index);
+      const fields = this.fields.at(-index);
       const { queryType, queryModel, queryInstructions } = splitQuery(query);
       const model = getModelBySlug(this.models, queryModel);
       if (queryType === "count") {
-        return { amount: result[0]["COUNT(*)"] };
+        return { amount: rows[0][0] };
       }
       const single = queryModel !== model.pluralSlug;
       if (single) {
-        return { record: this.formatRecord(model, result[0]) };
+        return { record: this.formatRow(fields, rows[0]) };
       }
       const pageSize = queryInstructions?.limitedTo;
       const output = {
-        records: result.map((resultItem) => {
-          return this.formatRecord(model, resultItem);
-        })
+        records: rows.map((row) => this.formatRow(fields, row))
       };
       if (pageSize && output.records.length > 0) {
         if (queryInstructions?.before || queryInstructions?.after) {
@@ -1585,6 +1661,8 @@ var Transaction = class {
 };
 var CLEAN_ROOT_MODEL = omit(ROOT_MODEL, ["system"]);
 export {
+  QUERY_SYMBOLS,
   CLEAN_ROOT_MODEL as ROOT_MODEL,
+  RoninError,
   Transaction
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronin/compiler",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "type": "module",
   "description": "Compiles RONIN queries to SQL statements.",
   "publishConfig": {