@ronin/compiler 0.8.8 → 0.9.0

package/README.md

@@ -39,25 +39,18 @@ You will just need to make sure that, once you [create a pull request](https://d
 The programmatic API of the RONIN compiler looks like this:
 
 ```typescript
-import {
-  compileQueries,
-
-  type Query,
-  type Model,
-  type Statement
-} from '@ronin/compiler';
-
-const queries: Array<Query> = [{
-  get: {
-    accounts: null
+import { Transaction } from '@ronin/compiler';
+
+const transaction = new Transaction([
+  {
+    create: { model: { slug: 'account' } }
+  },
+  {
+    get: { accounts: null }
   }
-}];
+]);
 
-const models: Array<Model> = [{
-  slug: 'account'
-}];
-
-const statements: Array<Statement> = compileQueries(queries, models);
+transaction.statements;
 // [{
 //   statement: 'SELECT * FROM "accounts"',
 //   params: [],
@@ -65,12 +58,45 @@ const statements: Array<Statement> = compileQueries(queries, models);
 // }]
 ```
 
+Once the RONIN queries have been compiled down to SQL statements, the statements can be
+executed and their results can be formatted by the compiler as well:
+
+```typescript
+// `rows` are provided by the database engine
+
+const results: Array<Result> = transaction.prepareResults(rows);
+```
+
+#### Types
+
+In total, the following types are being exported:
+
+```typescript
+import type {
+  Query,
+
+  Model,
+  ModelField,
+  ModelIndex,
+  ModelTrigger,
+  ModelPreset,
+
+  Statement,
+  Result
+} from '@ronin/compiler';
+```
+
 #### Options
 
 To fine-tune the behavior of the compiler, you can pass the following options:
 
 ```typescript
-compileQueries(queries, models, {
+new Transaction(queries, {
+  // A list of models that already existing inside the database.
+  models: [
+    { slug: 'account' }
+  ],
+
   // 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.
@@ -88,6 +114,16 @@ bun run dev
 
 Whenever you make a change to the source code, it will then automatically be transpiled again.
 
+### Mental Model
+
+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.
+
+Just like for the database, a transaction for the compiler defines an [atomic operation](https://www.sqlite.org/lang_transaction.html) in which a list of queries can be executed serially, and where each query can rely on the changes made by a previous one. In order to facilitate this, a programmatic interface that clarifies the accumulation of in-memory state is required (class instances).
+
+For example, if one query creates a new model, every query after it within the same transaction must be able to interact with the records of that model, or update the model itself, without roundtrips to the database, thereby requiring the accumulation of state while the transaction is being compiled.
+
+Furthermore, since every database transaction causes a [lock](https://www.sqlite.org/lockingv3.html), the database is inherently not locked between the execution of multiple transactions, which could cause the compilation inputs (e.g. models) of a `Transaction` to no longer be up-to-date. If the inputs have changed, a `new Transaction` should therefore be created.
+
 ### Running Tests
 
 The RONIN compiler has 100% test coverage, which means that every single line of code is tested automatically, to ensure that any change to the source code doesn't cause a regression.

package/dist/index.d.ts

@@ -5972,17 +5972,46 @@ type PublicModel<T extends Array<ModelField> = Array<ModelField>> = Omit<Partial
     identifiers?: Partial<Model['identifiers']>;
 };
 
-/**
- * Composes SQL statements for the provided RONIN queries.
- *
- * @param queries - The RONIN queries for which SQL statements should be composed.
- * @param models - A list of models.
- * @param options - Additional options to adjust the behavior of the statement generation.
- *
- * @returns The composed SQL statements.
- */
-declare const compileQueries: (queries: Array<Query>, models: Array<PublicModel>, options?: {
-    inlineParams?: boolean;
-}) => Array<Statement>;
+type Row = Record<string, unknown>;
+type NativeRecord = Record<string, unknown> & {
+    id: string;
+    ronin: {
+        createdAt: Date;
+        updatedAt: Date;
+    };
+};
+type SingleRecordResult = {
+    record: NativeRecord | null;
+};
+type MultipleRecordResult = {
+    records: Array<NativeRecord>;
+    moreAfter?: string;
+    moreBefore?: string;
+};
+type AmountResult = {
+    amount: number;
+};
+type Result = SingleRecordResult | MultipleRecordResult | AmountResult;
+
+declare class Transaction {
+    statements: Array<Statement>;
+    models: Array<Model>;
+    private queries;
+    constructor(queries: Array<Query>, options?: Parameters<typeof this.compileQueries>[2] & {
+        models?: Array<PublicModel>;
+    });
+    /**
+     * Composes SQL statements for the provided RONIN queries.
+     *
+     * @param queries - The RONIN queries for which SQL statements should be composed.
+     * @param models - A list of models.
+     * @param options - Additional options to adjust the behavior of the statement generation.
+     *
+     * @returns The composed SQL statements.
+     */
+    private compileQueries;
+    private formatRecord;
+    prepareResults(results: Array<Array<Row>>): Array<Result>;
+}
 
-export { type PublicModel as Model, type ModelField, type ModelIndex, type ModelPreset, type ModelTrigger, type Query, type Statement, compileQueries };
+export { type PublicModel as Model, type ModelField, type ModelIndex, type ModelPreset, type ModelTrigger, type Query, type Result, type Statement, Transaction };

package/dist/index.js

@@ -145,7 +145,8 @@ var composeFieldValues = (models, model, statementParams, instructionName, value
   );
   const collectStatementValue = options.type !== "fields";
   const symbol = getSymbol(value);
-  let conditionValue = value;
+  const syntax = WITH_CONDITIONS[options.condition || "being"](value);
+  let conditionValue = syntax[1];
   if (symbol) {
     if (symbol?.type === "expression") {
       conditionValue = parseFieldExpression(
@@ -159,11 +160,11 @@ var composeFieldValues = (models, model, statementParams, instructionName, value
       conditionValue = `(${compileQueryInput(symbol.value, models, statementParams).main.statement})`;
     }
   } else if (collectStatementValue) {
-    conditionValue = prepareStatementValue(statementParams, value);
+    conditionValue = prepareStatementValue(statementParams, conditionValue);
   }
   if (options.type === "fields") return conditionSelector;
   if (options.type === "values") return conditionValue;
-  return `${conditionSelector} ${WITH_CONDITIONS[options.condition || "being"](conditionValue, value)}`;
+  return `${conditionSelector} ${syntax[0]} ${conditionValue}`;
 };
 var composeConditions = (models, model, statementParams, instructionName, value, options) => {
   const isNested = isObject(value) && Object.keys(value).length > 0;
@@ -293,18 +294,18 @@ var getMatcher = (value, negative) => {
   return "=";
 };
 var WITH_CONDITIONS = {
-  being: (value, baseValue) => `${getMatcher(baseValue, false)} ${value}`,
-  notBeing: (value, baseValue) => `${getMatcher(baseValue, true)} ${value}`,
-  startingWith: (value) => `LIKE ${value}%`,
-  notStartingWith: (value) => `NOT LIKE ${value}%`,
-  endingWith: (value) => `LIKE %${value}`,
-  notEndingWith: (value) => `NOT LIKE %${value}`,
-  containing: (value) => `LIKE %${value}%`,
-  notContaining: (value) => `NOT LIKE %${value}%`,
-  greaterThan: (value) => `> ${value}`,
-  greaterOrEqual: (value) => `>= ${value}`,
-  lessThan: (value) => `< ${value}`,
-  lessOrEqual: (value) => `<= ${value}`
+  being: (value) => [getMatcher(value, false), value],
+  notBeing: (value) => [getMatcher(value, true), value],
+  startingWith: (value) => ["LIKE", `${value}%`],
+  notStartingWith: (value) => ["NOT LIKE", `${value}%`],
+  endingWith: (value) => ["LIKE", `%${value}`],
+  notEndingWith: (value) => ["NOT LIKE", `%${value}`],
+  containing: (value) => ["LIKE", `%${value}%`],
+  notContaining: (value) => ["NOT LIKE", `%${value}%`],
+  greaterThan: (value) => [">", value],
+  greaterOrEqual: (value) => [">=", value],
+  lessThan: (value) => ["<", value],
+  lessOrEqual: (value) => ["<=", value]
 };
 var handleWith = (models, model, statementParams, instruction, parentModel) => {
   const subStatement = composeConditions(
@@ -1350,33 +1351,73 @@ var compileQueryInput = (query, models, statementParams, options) => {
 };
 
 // src/index.ts
-var compileQueries = (queries, models, options) => {
-  const modelList = addSystemModels(models).map((model) => {
-    return addDefaultModelFields(model, true);
-  });
-  const modelListWithPresets = modelList.map((model) => {
-    return addDefaultModelPresets(modelList, model);
-  });
-  const dependencyStatements = [];
-  const mainStatements = [];
-  for (const query of queries) {
-    const statementValues = options?.inlineParams ? null : [];
-    const transformedQuery = transformMetaQuery(
-      modelListWithPresets,
-      dependencyStatements,
-      statementValues,
-      query
-    );
-    const result = compileQueryInput(
-      transformedQuery,
-      modelListWithPresets,
-      statementValues
-    );
-    dependencyStatements.push(...result.dependencies);
-    mainStatements.push(result.main);
+var Transaction = class {
+  statements;
+  models = [];
+  queries;
+  constructor(queries, options) {
+    const models = options?.models || [];
+    this.statements = this.compileQueries(queries, models, options);
+    this.queries = queries;
+  }
+  /**
+   * Composes SQL statements for the provided RONIN queries.
+   *
+   * @param queries - The RONIN queries for which SQL statements should be composed.
+   * @param models - A list of models.
+   * @param options - Additional options to adjust the behavior of the statement generation.
+   *
+   * @returns The composed SQL statements.
+   */
+  compileQueries = (queries, models, options) => {
+    const modelList = addSystemModels(models).map((model) => {
+      return addDefaultModelFields(model, true);
+    });
+    const modelListWithPresets = modelList.map((model) => {
+      return addDefaultModelPresets(modelList, model);
+    });
+    const dependencyStatements = [];
+    const mainStatements = [];
+    for (const query of queries) {
+      const statementValues = options?.inlineParams ? null : [];
+      const transformedQuery = transformMetaQuery(
+        modelListWithPresets,
+        dependencyStatements,
+        statementValues,
+        query
+      );
+      const result = compileQueryInput(
+        transformedQuery,
+        modelListWithPresets,
+        statementValues
+      );
+      dependencyStatements.push(...result.dependencies);
+      mainStatements.push(result.main);
+    }
+    this.models = modelListWithPresets;
+    return [...dependencyStatements, ...mainStatements];
+  };
+  formatRecord(model, record) {
+    const formattedRecord = { ...record };
+    for (const key in record) {
+      const { field } = getFieldFromModel(model, key, "to");
+      if (field.type === "json") {
+        formattedRecord[key] = JSON.parse(record[key]);
+        continue;
+      }
+      formattedRecord[key] = record[key];
+    }
+    return expand(formattedRecord);
+  }
+  prepareResults(results) {
+    return results.map((result, index) => {
+      const query = this.queries.at(-index);
+      const { queryModel } = splitQuery(query);
+      const model = getModelBySlug(this.models, queryModel);
+      return { record: this.formatRecord(model, result[0]) };
+    });
   }
-  return [...dependencyStatements, ...mainStatements];
 };
 export {
-  compileQueries
+  Transaction
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronin/compiler",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "type": "module",
   "description": "Compiles RONIN queries to SQL statements.",
   "publishConfig": {
@@ -33,6 +33,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.2",
+    "@ronin/engine": "0.0.2",
     "@types/bun": "1.1.10",
     "@types/title": "3.4.3",
     "tsup": "8.3.0",