Move MIT source code and API docs into this repo

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: "CI Full Run"
+on:
+  pull_request:
+    branches:
+      - main
+      - grok/*/*
+  push:
+    branches:
+      - main
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ["22.x"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install -g pnpm --force
+      - run: pnpm install
+      - run: pnpm run build
+      - run: pnpm run lint
+      - run: pnpm run test

.gitignore

@@ -2,6 +2,7 @@ node_modules
 package-lock.json
 yarn.lock
 pnpm-lock.yaml
+dist
 .DS_Store
 *.log
 *.tmp

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx"],
+      "options": { "parser": "typescript" }
+    }
+  ]
+}

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "mhutchie.git-graph",
+    "trentrand.git-rebase-shortcuts"
+  ]
+}

.vscode/tasks.json

@@ -1,6 +1,14 @@
 {
   "version": "2.0.0",
   "tasks": [
+    {
+      "label": "git grok: push local commits as individual PRs",
+      "detail": "Install git-grok first: https://github.com/dimikot/git-grok",
+      "type": "shell",
+      "command": "git grok",
+      "problemMatcher": [],
+      "hide": false
+    },
     {
       "label": "git rebase --interactive",
       "detail": "Opens a UI for interactive rebase (install \"Git rebase shortcuts\" extension).",

README.md

@@ -1,3 +1,15 @@
+# Ent Framework
+
+<div align="left"><figure><img src="gitbook/.gitbook/assets/logo-berkshire-swash.svg" alt="" width="375"><figcaption></figcaption></figure></div>
+
+The TypeScript library for working with microsharded PostgreSQL databases.
+
+* [Getting Started and Tutorials](https://ent-framework.net)
+* [API documentation](https://github.com/dimikot/ent-framework/blob/main/docs/globals.md)
+* [Source code](https://github.com/dimikot/ent-framework/tree/main/src)
+* [Ent Framework's Discord](https://discord.gg/QXvN6VTCKS)
+
+#### Core Features
 
 1. **Graph-like representation of entities.** With Ent Framework, you represent each Ent (a domain object of your business logic) as a TypeScript class with immutable properties. An Ent class instance maps to one row of some table in a relational database (like PostgreSQL). It may look similar to ORM, but has many aspects that traditional ORMs don't have.
 2. **Row-level security in a graph (privacy layer).** You manage data as a graph where each node is an Ent instance, and each edge is a field link (think of foreign keys) to other Ents. To be allowed to read (or update/delete) some Ent, you define a set of explicit rules like "user can read EntA if they can read EntB or EntC". And, consequently, in EntB you define its own set of rules, like "user can read EntB if they can read EntD".

barrelsby.json

@@ -0,0 +1,15 @@
+{
+  "name": "index",
+  "directory": [
+    "./src/abstract",
+    "./src/ent",
+    "./src/helpers",
+    "./src/pg",
+    "./src/tools"
+  ],
+  "exclude": [
+    "ent-framework\/.*\/__",
+    "ent-framework\/.*\/internal"
+  ],
+  "delete": true
+}

docker-compose.postgres.yml

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16
+    ports:
+      - "${PGPORT:?err}:${PGPORT}"
+    environment:
+      POSTGRES_PASSWORD: postgres
+      PGDATA: /tmp/postgresql
+      POSTGRES_INITDB_ARGS: "-c port=$PGPORT -c max_connections=2000 -c synchronous_commit=off -c wal_level=logical"
+    healthcheck:
+      test: "PGPORT=$PGPORT pg_isready -U postgres"
+      interval: 0.3s
+      timeout: 20s
+      retries: 10

docs/README.md

@@ -0,0 +1,33 @@
+**ent-framework**
+
+***
+
+# Ent Framework
+
+<div align="left"><figure><img src="_media/logo-berkshire-swash.svg" alt="" width="375"><figcaption></figcaption></figure></div>
+
+The TypeScript library for working with microsharded PostgreSQL databases.
+
+* [Getting Started and Tutorials](https://ent-framework.net)
+* [API documentation](https://github.com/dimikot/ent-framework/blob/main/docs/globals.md)
+* [Source code](https://github.com/dimikot/ent-framework/tree/main/src)
+* [Ent Framework's Discord](https://discord.gg/QXvN6VTCKS)
+
+#### Core Features
+
+1. **Graph-like representation of entities.** With Ent Framework, you represent each Ent (a domain object of your business logic) as a TypeScript class with immutable properties. An Ent class instance maps to one row of some table in a relational database (like PostgreSQL). It may look similar to ORM, but has many aspects that traditional ORMs don't have.
+2. **Row-level security in a graph (privacy layer).** You manage data as a graph where each node is an Ent instance, and each edge is a field link (think of foreign keys) to other Ents. To be allowed to read (or update/delete) some Ent, you define a set of explicit rules like "user can read EntA if they can read EntB or EntC". And, consequently, in EntB you define its own set of rules, like "user can read EntB if they can read EntD".
+3. **Query batching and coalescing.** Ent Framework holistically solves the "N+1 selects" problem commonly known in ORM world. You still write you code as if you work with individual Ents and individual IDs, and the framework magically takes care of sending batched requests (both read and write) to the underlying relational database. You do not work with lists and JOINs anymore.
+4. **Microsharding and replication lag tracking support out of the box.** Splitting your database horizontally is like a breeze now: Ent Framework takes care of routing the requests to the proper microshards. When scaling reads, Ent Framework knows whether a replica node is "good enough" for that particular query. It automatically uses the proper replica when possible, falling back to master when not.
+5. **Pluggable to your existing relational database.** If your project already uses some ORM or runs raw SQL queries, Ent Framework can be plugged in.
+6. **Tens of other features.** Some examples: cross-microshards foreign keys, composite fields, triggers, build-in caching etc.
+
+#### Installation
+
+```
+npm add ent-framework
+pnpm add ent-framework
+yarn add ent-framework
+```
+
+<div align="left"><figure><img src="https://github.com/clickup/ent-framework/actions/workflows/ci.yml/badge.svg?branch=main" alt="" width="188"><figcaption></figcaption></figure></div>

docs/classes/AllowIf.md

@@ -0,0 +1,77 @@
+[**ent-framework**](../README.md)
+
+***
+
+[ent-framework](../globals.md) / AllowIf
+
+# Class: AllowIf\<TInput\>
+
+Defined in: [src/ent/rules/AllowIf.ts:12](https://github.com/clickup/ent-framework/blob/master/src/ent/rules/AllowIf.ts#L12)
+
+Returns ALLOW if the predicate succeeds, otherwise SKIP.
+- Used mostly for read permission checks.
+- This rule may still throw an exception if the exception is a wild one (not
+  derived from EntAccessError).
+
+## Extends
+
+- [`Rule`](Rule.md)\<`TInput`\>
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TInput` *extends* `object` |
+
+## Constructors
+
+### new AllowIf()
+
+> **new AllowIf**\<`TInput`\>(`predicate`): [`AllowIf`](AllowIf.md)\<`TInput`\>
+
+Defined in: [src/ent/rules/Rule.ts:43](https://github.com/clickup/ent-framework/blob/master/src/ent/rules/Rule.ts#L43)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `boolean` \| `Promise`\<`boolean`\> |
+
+#### Returns
+
+[`AllowIf`](AllowIf.md)\<`TInput`\>
+
+#### Inherited from
+
+[`Rule`](Rule.md).[`constructor`](Rule.md#constructors)
+
+## Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="_tag"></a> `_TAG` | `"AllowIf"` |
+| <a id="predicate-1"></a> `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> |
+| <a id="name"></a> `name` | `string` |
+
+## Methods
+
+### evaluate()
+
+> **evaluate**(`vc`, `input`): `Promise`\<[`RuleResult`](../interfaces/RuleResult.md)\>
+
+Defined in: [src/ent/rules/AllowIf.ts:15](https://github.com/clickup/ent-framework/blob/master/src/ent/rules/AllowIf.ts#L15)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `vc` | [`VC`](VC.md) |
+| `input` | `TInput` |
+
+#### Returns
+
+`Promise`\<[`RuleResult`](../interfaces/RuleResult.md)\>
+
+#### Overrides
+
+[`Rule`](Rule.md).[`evaluate`](Rule.md#evaluate)

docs/classes/Batcher.md

@@ -0,0 +1,75 @@
+[**ent-framework**](../README.md)
+
+***
+
+[ent-framework](../globals.md) / Batcher
+
+# Class: Batcher\<TInput, TOutput\>
+
+Defined in: [src/abstract/Batcher.ts:19](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L19)
+
+Batcher is similar to DataLoader, but with a few important differences:
+1. It's strongly typed not only for the output, but for input too. And input
+   can be arbitrary, not only strings (e.g. rows).
+2. It does requests dedupping for all queries (including selects).
+3. It's not limited by read-only requests like DataLoader, and thus it
+   doesn't to any caching. Caching is delegated to some other layer (either
+   above Batcher or in Runner).
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TInput` |
+| `TOutput` |
+
+## Constructors
+
+### new Batcher()
+
+> **new Batcher**\<`TInput`, `TOutput`\>(`runner`, `batchDelayMs`, `disableBatching`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
+
+Defined in: [src/abstract/Batcher.ts:90](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L90)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `runner` | [`Runner`](Runner.md)\<`TInput`, `TOutput`\> |
+| `batchDelayMs` | `MaybeCallable`\<`number`\> |
+| `disableBatching` | `boolean` |
+
+#### Returns
+
+[`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
+
+## Methods
+
+### flushQueue()
+
+> `protected` **flushQueue**(): `Promise`\<`void`\>
+
+Defined in: [src/abstract/Batcher.ts:32](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L32)
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### run()
+
+> **run**(`input`, `annotation`): `Promise`\<`TOutput`\>
+
+Defined in: [src/abstract/Batcher.ts:96](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L96)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `input` | `TInput` |
+| `annotation` | [`QueryAnnotation`](../interfaces/QueryAnnotation.md) |
+
+#### Returns
+
+`Promise`\<`TOutput`\>

docs/classes/CanDeleteOutgoingEdge.md

@@ -0,0 +1,72 @@
+[**ent-framework**](../README.md)
+
+***
+
+[ent-framework](../globals.md) / CanDeleteOutgoingEdge
+
+# Class: CanDeleteOutgoingEdge\<TField\>
+
+Defined in: [src/ent/predicates/CanDeleteOutgoingEdge.ts:10](https://github.com/clickup/ent-framework/blob/master/src/ent/predicates/CanDeleteOutgoingEdge.ts#L10)
+
+Checks that an Ent available via a field can be deleted, or Ent doesn't exist
+(e.g. Ent is orphaned). See CanReadOutgoingEdge comments for more details.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TField` *extends* `string` |
+
+## Implements
+
+- [`Predicate`](../interfaces/Predicate.md)\<`Record`\<`TField`, `string` \| `null`\>\>
+
+## Constructors
+
+### new CanDeleteOutgoingEdge()
+
+> **new CanDeleteOutgoingEdge**\<`TField`\>(`field`, `toEntClass`): [`CanDeleteOutgoingEdge`](CanDeleteOutgoingEdge.md)\<`TField`\>
+
+Defined in: [src/ent/predicates/CanDeleteOutgoingEdge.ts:15](https://github.com/clickup/ent-framework/blob/master/src/ent/predicates/CanDeleteOutgoingEdge.ts#L15)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `field` | `TField` |
+| `toEntClass` | [`EntClass`](../interfaces/EntClass.md) |
+
+#### Returns
+
+[`CanDeleteOutgoingEdge`](CanDeleteOutgoingEdge.md)\<`TField`\>
+
+## Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="name"></a> `name` | `string` |
+| <a id="field-1"></a> `field` | `TField` |
+| <a id="toentclass-1"></a> `toEntClass` | [`EntClass`](../interfaces/EntClass.md) |
+
+## Methods
+
+### check()
+
+> **check**(`vc`, `row`): `Promise`\<`boolean`\>
+
+Defined in: [src/ent/predicates/CanDeleteOutgoingEdge.ts:22](https://github.com/clickup/ent-framework/blob/master/src/ent/predicates/CanDeleteOutgoingEdge.ts#L22)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `vc` | [`VC`](VC.md) |
+| `row` | `Record`\<`TField`, `null` \| `string`\> |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+#### Implementation of
+
+[`Predicate`](../interfaces/Predicate.md).[`check`](../interfaces/Predicate.md#check)