@entity-access/entity-access 1.0.1

package/README.md

@@ -0,0 +1,247 @@
+# Entity Access
+
+Inspired from Entity Framework Core, Entity Access is ORM for JavaScript runtime such as Node, YantraJS.
+
+
+# Project Status
+1. Beta - Postgres Driver
+2. Alpha - Sql Server Driver
+
+## Features
+1. Unit of Work and Repository Pattern
+2. Arrow function based query features with automatic joins.
+3. Automatic Migrations for missing schema - this is done for fast development and deployment.
+4. Sql functions such as LIKE
+5. Postgres Driver
+6. Sql Server Driver
+7. Automatic parameterization to safeguard sql injection attacks.
+
+## Upcoming Features
+1. Include
+2. Projection - Split query mode only, single level only.
+3. GroupBy
+
+### Unit of Work
+
+```typescript
+const db = new ShoppingContext();
+db.orders.add({
+    orderDate: new Date(),
+    userID,
+    orderItems: [
+        db.orderItems.add({
+            productID,
+            amount
+        })
+    ]
+});
+
+// save all in single transaction
+await db.saveChanges();
+```
+
+### Arrow function based query features
+
+Arrow function based query provides many benefits over tagged template literals or other fluent methods to build queries.
+1. Arrow functions are easy to visualize.
+2. You will get intellisense help to complete the query.
+3. You will get errors if the wrong data types are compared or used in computations.
+4. Change of property name will automatically refactor as typescript will keep references of where the property is used.
+
+Simple Query
+```typescript
+const db = new ShoppingContext();
+
+/// first parameter is set of parameters to pass to the query
+/// the reason it is first, is to help in intellisense.
+
+/// second parameter is an arrow function which returns a filter
+const q = db.orders.where({ userID }, (params) => (order) => order.userID === p.userID);
+```
+
+Query with Like operator
+```typescript
+/// Find all orders for specified customer
+/// Sql functions
+const userName = `akash%`;
+const q = db.orders.where({ userName },
+    (params) =>
+        (order) =>
+            Sql.text.like(
+                order.customer.userName,
+                p.userName
+            )
+);
+
+// note that the join will be performed automatically
+```
+
+### Typed Configurations
+```typescript
+class ShoppingContext {
+    products = this.model.register(Product);
+    orders = this.model.register(Order);
+    orderItems = this.model.register(OrderItem);
+}
+
+@Table("Products")
+class Product {
+
+    @Column({ key: true, autoGenerated: true })
+    productID: number;
+
+    orderItems: OrderItem[];
+}
+
+@Table("OrderItems")
+class OrderItem {
+
+    @Column({ key: true, autoGenerated: true })
+    orderItemID: number;
+
+    @Column()
+    productID: number;
+
+    @Column()
+    orderID: number;
+
+    /**
+     * Following configuration declares everything
+     * that will give compilation error if configured wrong.
+    */
+    @ForeignKey({
+        key: (orderItem) => orderItem.productID,
+        related: Product,
+        relatedProperty:(product) => product.orderItems
+    })
+    product: Product;
+
+}
+
+```
+
+## Query Examples
+
+### Compare operators
+
+#### Equality
+Both strict and non strict equality will result in
+simple equality comparison in SQL. Database provider
+may or may not convert them correctly, so we recommend
+using helper functions to convert before comparison.
+```typescript
+    // find all customer from orderID
+    const q = db.customers
+        // first we will send parameters
+        .where({ orderID },
+            // second we will write an arrow
+            // accepting parameters
+            (p) =>
+                // this is the arrow which will
+                // be converted to SQL
+                // you can write very limited set of
+                // expressions in this arrow function
+                (x) => x.orders.some(
+                    // This will results in exists or join
+                    // based on what level of nested
+                    // foreign key references are available
+                    (order) => order.orderID === p.orderID )
+        )
+
+```
+
+Above expression will result in following filter expression
+```sql
+    EXISTS (
+        SELECT 1
+        FROM Orders as o1
+        WHERE x.customerID = o1.orderID
+            AND o1.orderID = $1
+    )
+```
+
+#### Like
+
+To use `LIKE` operator, `Sql.text.like` method must be used
+as it is. Query compiler will only match everything starting
+with `Sql.` and it will inject available operator conversion.
+
+You don't have to worry about sql injection as each parameter
+passed will be sent as a sql parameter and not as a literal.
+
+```typescript
+    const prefix = `${name}%`;
+    db.customers.where({ prefix },
+        (p) =>
+            (customer) => Sql.text.like(customer.firstName, p.prefix)
+                || Sql.text.like(customer.lastName p.prefix)
+    )
+```
+
+#### Sql Text Functions
+For other sql text functions you can use `Sql.text.startsWith`, `Sql.text.endsWith`, `Sql.text.left`... etc as shown below.
+```typescript
+    db.customers.where({ prefix },
+        (p) =>
+            (customer) => Sql.text.startsWith(customer.firstName, p.prefix)
+                || Sql.text.startsWith(customer.lastName p.prefix)
+    )
+```
+
+#### Sql date functions
+Just as text functions you can also use date functions as shown below.
+```typescript
+    const year = (new Date()).getFullYear();
+    // get count of all orders of this year...
+    db.orders.where({ year },
+        (p) =>
+            (order) => Sql.date.yearOf(order.orderDate) === p.year
+    )
+
+    // above example is only for illustrations only, it will not use index.
+    // for index usage, please consider window function shown below.
+    const start:Date = /* start date */;
+    const end:Date = /* start date */;
+    // get count of all orders of this year...
+    db.orders.where({ start, end },
+        (p) =>
+            (order) => p.start <= order.orderDate && order.orderDate >= p.end
+    )
+
+```
+
+### OrderBy
+```typescript
+    q.orderBy({}, (p) => (x) => x.orderDate)
+    .thenBy({}, (p) => (x) => x.customer.firstName)
+```
+
+### Limit/Offset
+```typescript
+    q = q.orderByDescending({}, (p) => (x) => x.orderDate)
+    .thenBy({}, (p) => (x) => x.customer.firstName)
+    .limit(50)
+    .offset(50);
+```
+
+### Enumerate
+```typescript
+    for await(const product of q.enumerate()) {
+        //
+    }
+```
+
+### First / First or Fail
+```typescript
+    // it will return first product or null
+    const firstProduct = await q.first();
+
+    // it will throw and exception if product was not
+    // found
+    const firstProduct = await q.firstOrFail();
+```
+
+### Count
+```typescript
+    const total = await q.count();
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@entity-access/entity-access",
+  "version": "1.0.1",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --enable-source-maps ./test.js",
+    "test-db": "node --enable-source-maps ./test.js test-db"
+  },
+  "type": "module",
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@babel/parser": "^7.22.5",
+    "@babel/types": "^7.22.5",
+    "pg": "^8.11.1",
+    "pg-cursor": "^2.10.1",
+    "reflect-metadata": "^0.1.13",
+    "tcp-port-used": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/mssql": "^8.1.2",
+    "@types/node": "^20.3.2",
+    "@types/pg": "^8.10.2",
+    "@types/pg-cursor": "^2.7.0",
+    "@typescript-eslint/eslint-plugin": "^5.59.9",
+    "@typescript-eslint/parser": "^5.59.9",
+    "eslint": "^8.42.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-jsdoc": "^46.2.6",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-prefer-arrow": "^1.2.3",
+    "eslint-plugin-promise": "^6.1.1",
+    "eslint-plugin-react": "^7.32.2",
+    "mssql": "^9.1.1"
+  }
+}

package/src/TestRunner.ts

@@ -0,0 +1,2 @@
+import { readdir } from "fs/promises";
+import PostgreSqlDriver from "./drivers/postgres/PostgreSqlDriver.js";

package/src/common/cache/InstanceCache.ts

@@ -0,0 +1,14 @@
+export default function InstanceCache(target: any, key: string): void {
+
+    Object.defineProperty(target, key, {
+        get() {
+            const value = this[key];
+            Object.defineProperty(this, key, {
+                value,
+            });
+            return value;
+        },
+        configurable: true
+    });
+
+}

package/src/common/cache/TimedCache.ts

@@ -0,0 +1,74 @@
+export default class TimedCache<TKey = any, T = any> {
+
+    private map: Map<TKey,{ value: any, expire: number, ttl: number, dispose?: (item: any) => any }> = new Map();
+
+    constructor(private ttl = 15000) {
+        // intentional
+        setInterval((x) => x.clear(), this.ttl, this);
+    }
+
+    delete(key: any) {
+        this.map.delete(key);
+    }
+
+    getOrCreate(key: TKey, factory: (k: TKey) => T, ttl: number = 15000) {
+        let item = this.map.get(key);
+        if (!item) {
+            item = { value: factory(key), ttl, expire: Date.now() + ttl };
+            this.map.set(key, item);
+        } else {
+            item.expire = Date.now() + ttl;
+        }
+        return item.value as T;
+    }
+
+    getOrCreateAsync(
+        key: TKey,
+        factory: (k: TKey) => Promise<T>,
+        ttl: number = 15000,
+        dispose?: ((item: T) => any)
+    ): Promise<T> {
+        let item = this.map.get(key);
+        if (!item) {
+            item = { value: factory(key), ttl, expire: Date.now() + ttl, dispose };
+            this.map.set(key, item);
+            // we need to make sure we do not cache
+            // the promise if it fails
+            item.value.catch(() => {
+                this.map.delete(key);
+            });
+            if (dispose) {
+                item.value.then((r) => {
+                    item.dispose = () => dispose(r);
+                });
+            }
+        } else {
+            item.expire = Date.now() + ttl;
+        }
+        return item.value;
+    }
+
+    private clear(): void {
+        const expired = [];
+        const now = Date.now();
+        for (const [key, value] of this.map.entries()) {
+            if(value.expire < now) {
+                expired.push(key);
+                // call dispose..
+                try {
+                    const r = value.dispose?.(value.value);
+                    if (r?.then) {
+                        r.catch(() => void 0);
+                    }
+                } catch (error) {
+                    console.error(error);
+                }
+            }
+        }
+        for (const key of expired) {
+            this.map.delete(key);
+        }
+    }
+
+
+}

package/src/common/symbols/symbols.ts

@@ -0,0 +1,2 @@
+export const modelSymbol = Symbol("model");
+export const contextSymbol = Symbol("context");

package/src/common/usingAsync.ts

@@ -0,0 +1,24 @@
+
+export interface IDisposable {
+
+    end?():any;
+    dispose?(): any;
+    close?(): any;
+
+}
+
+
+export default async function usingAsync<T extends IDisposable>(d: T, fx: (p:T) => Promise<any>) {
+    try {
+        const r = fx(d);
+        if (r?.then) {
+            await r;
+        }
+        return r;
+    } finally {
+        const r = d.dispose?.() ?? d.end?.() ?? d.close?.();
+        if (r?.then) {
+            await r;
+        }
+    }
+}

package/src/compiler/ISqlHelpers.ts

@@ -0,0 +1,30 @@
+import { ISql } from "../sql/ISql.js";
+
+type IFunction = ( ... a: any[]) => any;
+
+type others = Omit<ISql, "in">;
+
+type IStringReturn<T extends IFunction> = (... p: Parameters<T>) => string;
+
+type transformed<T> = {
+    [P in keyof T]: T[P] extends IFunction ? IStringReturn<T[P]> : transformed<T[P]>;
+};
+
+export type ISqlHelpers = transformed<ISql>;
+
+export const flattenHelpers = (f, name, target = {}) => {
+    for (const key in f) {
+        if (Object.prototype.hasOwnProperty.call(f, key)) {
+            const element = f[key];
+            if (typeof element === "function") {
+                target[name + "." + key] = element;
+                continue;
+            }
+            if (typeof element !== "object") {
+                continue;
+            }
+            flattenHelpers(element, name + "." + key, target);
+        }
+    }
+    return target;
+};

package/src/compiler/QueryCompiler.ts

@@ -0,0 +1,88 @@
+import { IClassOf } from "../decorators/IClassOf.js";
+import ExpressionToSql from "../query/ast/ExpressionToSql.js";
+import { ISqlMethodTransformer, IStringTransformer, ITextOrFunctionArray } from "../query/ast/IStringTransformer.js";
+import { Expression, PlaceholderExpression } from "../query/ast/Expressions.js";
+import SqlLiteral from "../query/ast/SqlLiteral.js";
+import ArrowToExpression from "../query/parser/ArrowToExpression.js";
+import PostgreSqlMethodTransformer from "./postgres/PostgreSqlMethodTransformer.js";
+import EntityType from "../entity-query/EntityType.js";
+import { EntitySource } from "../model/EntitySource.js";
+import { IEntityQuery } from "../model/IFilterWithParameter.js";
+import { SourceExpression } from "../model/SourceExpression.js";
+
+export default class QueryCompiler {
+
+    public static instance = new QueryCompiler();
+
+    public readonly arrowToExpression: typeof ArrowToExpression;
+    public readonly expressionToSql: typeof ExpressionToSql;
+
+    public readonly quotedLiteral: IStringTransformer;
+    public readonly escapeLiteral: IStringTransformer;
+
+    public readonly sqlMethodTransformer: ISqlMethodTransformer;
+
+    constructor(
+        {
+            arrowToExpression = ArrowToExpression,
+            expressionToSql = ExpressionToSql,
+            quotedLiteral = JSON.stringify,
+            escapeLiteral = SqlLiteral.escapeLiteral,
+            sqlMethodTransformer = PostgreSqlMethodTransformer
+        }: Partial<QueryCompiler> = {}
+    ) {
+        this.arrowToExpression = arrowToExpression;
+        this.expressionToSql = expressionToSql;
+        this.escapeLiteral = escapeLiteral;
+        this.quotedLiteral = quotedLiteral;
+        this.sqlMethodTransformer = sqlMethodTransformer;
+    }
+
+    public execute<P = any, T = any>(parameters: P, fx: (p: P) => (x: T) => any, source?: SourceExpression) {
+        const { param, target , body } = this.arrowToExpression.transform(fx);
+        const exp = new this.expressionToSql(source, param, target, this);
+        const query = exp.visit(body);
+        return this.invoke(query, parameters);
+    }
+
+    public compileToExpression(source: SourceExpression, p: any, fx: (p1) => (x) => any) {
+        const { param, target , body } = this.arrowToExpression.transform(fx);
+        const exp = new this.expressionToSql(source, param, target, this);
+        const visited = exp.visit(body);
+        return PlaceholderExpression.create({
+            expression: () => visited.map((x) => typeof x === "function" ? () => x(p) : x)
+        });
+    }
+
+    public compile( source: SourceExpression , fx: (p) => (x) => any) {
+        const { param, target , body } = this.arrowToExpression.transform(fx);
+        const exp = new this.expressionToSql(source, param, target, this);
+        return exp.visit(body);
+    }
+
+    public compileExpression(exp: Expression) {
+        const toSql = new this.expressionToSql(null, void 0, void 0, this);
+        const query = toSql.visit(exp);
+        return this.invoke(query);
+    }
+
+    private invoke(query: ITextOrFunctionArray, p: any = {}) {
+        let text = "";
+        const values = [];
+        for (const iterator of query) {
+            if (typeof iterator === "string") {
+                text += iterator;
+                continue;
+            }
+            let value = iterator;
+            if (typeof iterator === "function") {
+                value = iterator(p);
+            }
+
+            values.push(value);
+            text += "$" + values.length;
+        }
+        return { text, values };
+    }
+
+}

package/src/compiler/postgres/PostgreSqlMethodTransformer.ts

@@ -0,0 +1,83 @@
+
+import { prepareAny } from "../../query/ast/IStringTransformer.js";
+import { ISqlHelpers, flattenHelpers } from "../ISqlHelpers.js";
+
+export const PostgreSqlHelper: ISqlHelpers = {
+    in(a, array) {
+        return prepareAny `${a} IN ${array}`;
+    },
+    date: {
+        addDays(d, n) {
+            return prepareAny `(${d} + (${n} * interval '1 day'))`;
+        },
+        addHours(d, n) {
+            return prepareAny `(${d} + (${n} * interval '1 hour'))`;
+        },
+        addMinutes(d, n) {
+            return prepareAny `(${d} + (${n} * interval '1 minute'))`;
+        },
+        addMonths(d, n) {
+            return prepareAny `(${d} + (${n} * interval '1 month'))`;
+        },
+        addSeconds(d, n) {
+            return prepareAny `(${d} + (${n} * interval '1 second'))`;
+        },
+        addYears(d, n) {
+            return prepareAny `(${d} + (${n} * interval '1 year'))`;
+        },
+        dayOf(d) {
+            return prepareAny `DATE_PART(${d}, day)`;
+        },
+        hourOf(d) {
+            return prepareAny `DATE_PART(${d}, hour)`;
+        },
+        minuteOf(d) {
+            return prepareAny `DATE_PART(${d}, minute)`;
+        },
+        monthOf(d) {
+            return prepareAny `DATE_PART(${d}, month)`;
+        },
+        secondOf(d) {
+            return prepareAny `DATE_PART(${d}, second)`;
+        },
+        yearOf(d) {
+            return prepareAny `DATE_PART(${d}, year)`;
+        },
+    },
+    text: {
+        concat(...p) {
+            return prepareAny `CONCAT(${p.join(",")})`;
+        },
+        endsWith(text, test) {
+            return prepareAny `strpos(${text}, ${test}) = length(${text}) - length(${test})`;
+        },
+        iLike(text, test) {
+            return prepareAny `(${text} iLike ${test})`;
+        },
+        indexOf(text, test) {
+            return prepareAny `strpos(${text}, ${test})`;
+        },
+        left(text, length) {
+            return prepareAny `left(${text}, ${length})`;
+        },
+        like(text, test) {
+            return prepareAny `(${text} LIKE ${test})`;
+        },
+        right(text, length) {
+            return prepareAny `right(${text}, ${length})`;
+        },
+        startsWith(text, test) {
+            return prepareAny `starts_with(${text}, ${test})`;
+        },
+    }
+};
+
+const names = flattenHelpers(PostgreSqlHelper, "Sql");
+
+export default function PostgreSqlMethodTransformer(callee: string, args: any[]): string {
+    const name = names[callee];
+    if (!name) {
+        return;
+    }
+    return names[callee]?.(... args);
+}

package/src/compiler/sql-server/SqlServerSqlMethodTransformer.ts

@@ -0,0 +1,83 @@
+
+import { prepareAny } from "../../query/ast/IStringTransformer.js";
+import { ISqlHelpers, flattenHelpers } from "../ISqlHelpers.js";
+
+export const SqlServerSqlHelper: ISqlHelpers = {
+    in(a, array) {
+        return prepareAny `${a} IN ${array}`;
+    },
+    date: {
+        addDays(d, n) {
+            return prepareAny `DateAdd(DAY, ${d}, ${n})`;
+        },
+        addHours(d, n) {
+            return prepareAny `DateAdd(HOUR, ${d}, ${n})`;
+        },
+        addMinutes(d, n) {
+            return prepareAny `DateAdd(MINUTE, ${d}, ${n})`;
+        },
+        addMonths(d, n) {
+            return prepareAny `DateAdd(MONTH, ${d}, ${n})`;
+        },
+        addSeconds(d, n) {
+            return prepareAny `DateAdd(SECOND, ${d}, ${n})`;
+        },
+        addYears(d, n) {
+            return prepareAny `DateAdd(YEAR, ${d}, ${n})`;
+        },
+        dayOf(d) {
+            return prepareAny `DATE_PART(day, ${d})`;
+        },
+        hourOf(d) {
+            return prepareAny `DATE_PART(hour, ${d})`;
+        },
+        minuteOf(d) {
+            return prepareAny `DATE_PART(minute, ${d})`;
+        },
+        monthOf(d) {
+            return prepareAny `DATE_PART(month, ${d})`;
+        },
+        secondOf(d) {
+            return prepareAny `DATE_PART(second, ${d})`;
+        },
+        yearOf(d) {
+            return prepareAny `DATE_PART(year, ${d})`;
+        },
+    },
+    text: {
+        concat(...p) {
+            return prepareAny `CONCAT(${p.join(",")})`;
+        },
+        endsWith(text, test) {
+            return prepareAny `CHARINDEX(${text}, ${test}) = LEN(${text}) - LEN(${test})`;
+        },
+        iLike(text, test) {
+            return prepareAny `(${text} like ${test})`;
+        },
+        indexOf(text, test) {
+            return prepareAny `CHARINDEX(${text}, ${test})`;
+        },
+        left(text, length) {
+            return prepareAny `left(${text}, ${length})`;
+        },
+        like(text, test) {
+            return prepareAny `(${text} LIKE ${test})`;
+        },
+        right(text, length) {
+            return prepareAny `right(${text}, ${length})`;
+        },
+        startsWith(text, test) {
+            return prepareAny `CHARINDEX(${text}, ${test}) = 1`;
+        },
+    }
+};
+
+const names = flattenHelpers(SqlServerSqlHelper, "Sql");
+
+export default function SqlServerSqlMethodTransformer(callee: string, args: any[]): string {
+    const name = names[callee];
+    if (!name) {
+        return;
+    }
+    return names[callee]?.(... args);
+}