uql-orm 0.84.0 → 0.85.0

package/README.md

@@ -185,7 +185,7 @@ Only the entities in `include` are served: a `$populate: { author: true }` here
 - **Type-safe to the leaf, nothing to generate.** Every key is checked against your entity, down into populated relations and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths, so `$like` on a numeric column is a compile error. No `.prisma` file, no generated client.
 - **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) reads a to-many inside the parent's statement, so a read is one round trip. Nothing is lazy, so nothing fires behind your back in a serializer.
 - **Light.** Zero runtime dependencies and every dialect in one package, yet `uql-orm/postgres` is about 27 kB gzipped. See [what we deleted to get there](https://uql-orm.dev/blog/zero-dependencies).
-- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), and [drift checks](https://uql-orm.dev/migrations) that catch a database that no longer matches.
+- **The hard things are built in.** [Semantic and vector search](https://uql-orm.dev/ai-semantic-search), [multi-tenant filters you cannot bypass by accident](https://uql-orm.dev/multi-tenancy), [soft-delete with restore](https://uql-orm.dev/entities/soft-delete), [streaming](https://uql-orm.dev/querying/streaming), [drift checks](https://uql-orm.dev/migrations) that catch a database that no longer matches, and [Better Auth](https://uql-orm.dev/better-auth) on every engine.
 - **The fastest ORM.** On a full PostgreSQL round trip it adds the least over hand-written driver code of any ORM in our open-source [benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), on Bun, Node and Deno alike. The same benchmark [scores the types](https://github.com/rogerpadilla/ts-orm-benchmark#type-safety) by compiling ordinary mistakes in each ORM's API: UQL is the only one that catches them all.
 
 ## Get started

package/dist/betterAuth/authEntities.d.ts

@@ -0,0 +1,7 @@
+import type { BetterAuthOptions } from 'better-auth';
+import type { Type } from '../type/index.js';
+/**
+ * The entities Better Auth's tables are for these options, its core tables and every plugin's: list them
+ * in `uql.config.ts` so `uql-migrate` creates and migrates them with the rest.
+ */
+export declare function authEntities(options: BetterAuthOptions): Type<object>[];

package/dist/betterAuth/authEntities.js

@@ -0,0 +1,154 @@
+import { getAuthTables } from 'better-auth/db';
+import { defineEntity, defineField, defineId, defineIndex, defineRelation } from '../entity/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
+/**
+ * The entities Better Auth's tables are for these options, its core tables and every plugin's: list them
+ * in `uql.config.ts` so `uql-migrate` creates and migrates them with the rest.
+ */
+export function authEntities(options) {
+    const shapes = shapesOf(options);
+    // A field type that is a constructor keyed by its name, which JSON would drop.
+    const key = JSON.stringify(shapes, (_, value) => (typeof value === 'function' ? value.name : value));
+    let entities = defined.get(key);
+    if (!entities) {
+        entities = defineTables(shapes);
+        defined.set(key, entities);
+    }
+    return [...entities];
+}
+/**
+ * Each set of tables defined so far, by its shapes: kept, since an adapter built on it may still be
+ * reading, and a table defined twice for one shape would be two entities over one table.
+ */
+const defined = new Map();
+/** Defines every table at once, since each one's foreign keys point at the others. */
+function defineTables(shapes) {
+    const byName = Object.fromEntries(shapes.map(({ name }) => [
+        name,
+        {
+            [name]: class {
+            },
+        }[name],
+    ]));
+    for (const { name, id, fields, indexes } of shapes) {
+        const entity = byName[name];
+        defineId(entity, 'id', id);
+        for (const field of fields) {
+            defineField(entity, field.name, field.options);
+            const { references } = field;
+            if (references) {
+                defineRelation(entity, `${field.name}Ref`, {
+                    entity: () => byName[references.table],
+                    cardinality: 'm1',
+                    references: (local, foreign) => [{ local: local[field.name], foreign: foreign[references.column] }],
+                    onDelete: references.onDelete,
+                });
+            }
+        }
+        for (const index of indexes) {
+            defineIndex(entity, { ...index, columns: (refs) => index.columns.map((column) => refs[column]) });
+        }
+        defineEntity(entity, { name });
+    }
+    return Object.values(byName);
+}
+/** Better Auth's schema as the tables UQL defines, every reference resolved to the column it points at. */
+function shapesOf(options) {
+    const schema = getAuthTables(options);
+    const id = keyOf(options);
+    const columnOf = (fields, key) => fields[key]?.fieldName ?? key;
+    // Refused rather than left for the schema build, which drops a foreign key whose column it cannot find.
+    const referenceOf = ({ model, field, onDelete = 'cascade' }) => {
+        const table = schema[model] ?? Object.values(schema).find(({ modelName }) => modelName === model);
+        const column = table?.fields[field];
+        if (!table || (field !== 'id' && !column)) {
+            throw new UqlUsageError(`a Better Auth field references '${model}.${field}', which its schema does not have`);
+        }
+        return {
+            // Every foreign key is indexed, so it takes the type an indexed copy of the column it points at would.
+            type: column ? typeOf({ ...column, index: true }) : id.type,
+            references: {
+                table: table.modelName,
+                column: column ? columnOf(table.fields, field) : 'id',
+                onDelete: ON_DELETE[onDelete],
+            },
+        };
+    };
+    return Object.values(schema).map((table) => ({
+        name: table.modelName,
+        id,
+        fields: Object.entries(table.fields).map(([key, field]) => {
+            const name = columnOf(table.fields, key);
+            const reference = field.references && referenceOf(field.references);
+            return {
+                name,
+                options: {
+                    name,
+                    type: reference?.type ?? typeOf(field),
+                    nullable: field.required === false,
+                    unique: field.unique,
+                    index: field.index,
+                    defaultValue: staticDefault(field),
+                },
+                references: reference?.references,
+            };
+        }),
+        indexes: (table.indexes ?? []).map(({ fields, unique, name }) => ({
+            columns: fields.map((key) => columnOf(table.fields, key)),
+            unique,
+            name,
+        })),
+    }));
+}
+/** The key: Better Auth's own string, its UUID, or the database's number; a key left to the database otherwise is refused. */
+function keyOf(options) {
+    const generateId = options.advanced?.database?.generateId;
+    if (generateId === false) {
+        throw new UqlUsageError("Better Auth's 'generateId: false' leaves the key to the database, which it can generate in more than one " +
+            "way: set 'serial' for a number or 'uuid' for a UUID");
+    }
+    if (generateId === 'serial') {
+        return { type: Number, autoIncrement: true };
+    }
+    return { type: generateId === 'uuid' ? 'uuid' : String };
+}
+/**
+ * A field's column type. Text is `text` unless something indexes it, which a column of unbounded length
+ * cannot be on MySQL; a list of allowed values is text too, since Better Auth checks them itself and a
+ * database check on them would need a migration each time one is added.
+ */
+function typeOf(field) {
+    const { type } = field;
+    if (type === 'string' || Array.isArray(type)) {
+        return field.unique || field.index || field.sortable ? String : 'text';
+    }
+    switch (type) {
+        case 'number':
+            return field.bigint ? BigInt : Number;
+        case 'boolean':
+            return Boolean;
+        case 'date':
+            return Date;
+        case 'json':
+        case 'string[]':
+        case 'number[]':
+            return 'json';
+    }
+}
+/**
+ * The default a column takes in the database, as Better Auth's own migrator gives one: a plain value on a
+ * text, number or boolean field, so a required column added to a populated table has one to backfill. A
+ * nullable unique column gets none, `NULL` being its only backfill two rows can share.
+ */
+function staticDefault({ type, defaultValue, unique, required }) {
+    const plain = typeof defaultValue === 'string' || typeof defaultValue === 'number' || typeof defaultValue === 'boolean';
+    const typed = type === 'string' || type === 'number' || type === 'boolean';
+    return plain && typed && !(unique && required === false) ? defaultValue : undefined;
+}
+const ON_DELETE = {
+    cascade: 'CASCADE',
+    'no action': 'NO ACTION',
+    restrict: 'RESTRICT',
+    'set null': 'SET NULL',
+    'set default': 'SET DEFAULT',
+};

package/dist/betterAuth/index.d.ts

@@ -0,0 +1,2 @@
+export * from './authEntities.js';
+export * from './uqlAdapter.js';

package/dist/betterAuth/index.js

@@ -0,0 +1,2 @@
+export * from './authEntities.js';
+export * from './uqlAdapter.js';

package/dist/betterAuth/uqlAdapter.d.ts

@@ -0,0 +1,16 @@
+import type { BetterAuthOptions } from 'better-auth';
+import { type DBAdapter, type DBAdapterDebugLogOption } from 'better-auth/adapters';
+import type { QuerierPool } from '../type/index.js';
+export type UqlAdapterOptions = {
+    readonly debugLogs?: DBAdapterDebugLogOption;
+    /**
+     * Whether Better Auth runs its multi-step writes in one transaction: on wherever the engine has them,
+     * so off on D1. A standalone MongoDB, which has them only as a replica set, needs `false`.
+     */
+    readonly transaction?: boolean;
+};
+/**
+ * Better Auth on a UQL pool, on every engine UQL runs on: `betterAuth({ database: uqlAdapter(pool) })`.
+ * Its tables are the entities {@link authEntities} returns, which `uql-migrate` creates like any other.
+ */
+export declare function uqlAdapter(pool: QuerierPool, opts?: UqlAdapterOptions): (options: BetterAuthOptions) => DBAdapter<BetterAuthOptions>;

package/dist/betterAuth/uqlAdapter.js

@@ -0,0 +1,155 @@
+import { createAdapterFactory, } from 'better-auth/adapters';
+import { likeLiteral } from '../dialect/operators.js';
+import { getMeta, idOf } from '../entity/index.js';
+import { whereIds } from '../util/dialect.util.js';
+import { entityName } from '../util/object.util.js';
+import { UqlUsageError } from '../util/uqlError.js';
+import { authEntities } from './authEntities.js';
+/**
+ * Better Auth on a UQL pool, on every engine UQL runs on: `betterAuth({ database: uqlAdapter(pool) })`.
+ * Its tables are the entities {@link authEntities} returns, which `uql-migrate` creates like any other.
+ */
+export function uqlAdapter(pool, opts = {}) {
+    const transactions = opts.transaction ?? pool.dialect.features.transactions;
+    return (options) => {
+        const entities = Object.fromEntries(authEntities(options).map((entity) => [entityName(getMeta(entity)), entity]));
+        const on = (querier, inTransaction) => createAdapterFactory({
+            config: {
+                adapterId: 'uql',
+                adapterName: 'UQL',
+                debugLogs: opts.debugLogs,
+                supportsJSON: true,
+                supportsDates: true,
+                supportsBooleans: true,
+                supportsNumericIds: true,
+                supportsArrays: true,
+                // The same adapter over the transaction's querier, as Better Auth's own adapters rebuild theirs.
+                transaction: transactions && !inTransaction ? (callback) => pool.transaction((trx) => callback(on(trx, true))) : false,
+            },
+            adapter: ({ getFieldName }) => methodsOf(querier, entities, getFieldName),
+        })(options);
+        return on(pool, false);
+    };
+}
+/**
+ * Better Auth's database methods over `querier`, its tables by the names its factory checked each `model`
+ * against. Only `where` arrives in database names; the rest are mapped here.
+ */
+function methodsOf(querier, entities, getFieldName) {
+    const select = (model, fields) => fields?.length ? Object.fromEntries(fields.map((field) => [getFieldName({ model, field }), true])) : undefined;
+    const filter = (where) => ({ $where: whereOf(where) });
+    /**
+     * Writes `payload` to the first row `where` finds, pinned to that row while it still matches `where`,
+     * and reads it back: `null` where none matched, or a concurrent write moved the row past the guard first.
+     */
+    const updateOne = async (model, where, payload) => {
+        const entity = entities[model];
+        const row = await querier.findOne(entity, filter(where));
+        if (!row) {
+            return null;
+        }
+        const meta = getMeta(entity);
+        const id = idOf(meta, row);
+        const pinned = { $where: { $and: [whereOf(where), whereIds(meta, id)] } };
+        const changed = await querier.updateMany(entity, pinned, payload);
+        return changed ? asRow(await querier.findOneById(entity, id)) : null;
+    };
+    return {
+        async create({ model, data }) {
+            const entity = entities[model];
+            const id = await querier.insertOne(entity, data);
+            // The row as stored, which Better Auth's SQL adapters return too: a column left out reads its default.
+            const row = id === undefined ? undefined : await querier.findOneById(entity, id);
+            if (!row) {
+                throw new UqlUsageError(`Better Auth inserted a '${model}' row it cannot read back: does a filter hide it?`);
+            }
+            return asRow(row);
+        },
+        async findOne({ model, modelKey = model, where, select: fields }) {
+            return asRow(await querier.findOne(entities[model], { ...filter(where), $select: select(modelKey, fields) }));
+        },
+        async findMany({ model, modelKey = model, where = [], select: fields, sortBy, offset, limit }) {
+            const rows = await querier.findMany(entities[model], {
+                ...filter(where),
+                $select: select(modelKey, fields),
+                $sort: sortBy && { [getFieldName({ model: modelKey, field: sortBy.field })]: sortBy.direction },
+                $skip: offset,
+                $limit: limit,
+            });
+            return rows.map((row) => asRow(row));
+        },
+        count({ model, where = [] }) {
+            return querier.count(entities[model], filter(where));
+        },
+        update({ model, where, update }) {
+            return updateOne(model, where, payloadOf(update));
+        },
+        // `$inc` adds in the statement, so racing increments all land, where a read-then-write would retry.
+        incrementOne({ model, where, increment, set }) {
+            const steps = Object.fromEntries(Object.entries(increment).map(([field, $inc]) => [field, { $inc }]));
+            return updateOne(model, where, { ...set, ...steps });
+        },
+        updateMany({ model, where, update }) {
+            return querier.updateMany(entities[model], filter(where), update, { unfiltered: !where.length });
+        },
+        async delete({ model, where }) {
+            // Unlike `deleteMany`, never unfiltered: UQL refuses one naming no row.
+            await querier.deleteMany(entities[model], filter(where));
+        },
+        deleteMany({ model, where }) {
+            return querier.deleteMany(entities[model], filter(where), { unfiltered: !where.length });
+        },
+    };
+}
+/**
+ * A row as the type Better Auth asks for, `null` for none: each method lets its caller name the shape of
+ * its own table, which no query can check, so this is the one place UQL takes that on trust.
+ */
+function asRow(row) {
+    return (row ?? null);
+}
+/** An update's payload, which Better Auth types as anything and always sends as a row of fields. */
+function payloadOf(update) {
+    if (typeof update !== 'object' || update === null) {
+        throw new UqlUsageError('Better Auth sent an update that is not a row of fields');
+    }
+    return update;
+}
+/**
+ * Better Auth's clauses as one `$where`: all of those joined by `AND`, and any of those joined by `OR`.
+ * Each clause is an entry of its own, since two on one field would overwrite each other in one map.
+ */
+function whereOf(where) {
+    const all = where.filter((clause) => clause.connector === 'AND').map(clauseOf);
+    const any = where.filter((clause) => clause.connector === 'OR').map(clauseOf);
+    const $where = {};
+    if (all.length)
+        $where['$and'] = all;
+    if (any.length)
+        $where['$or'] = any;
+    return $where;
+}
+/** One clause; ignoring case applies where every value is text, as Better Auth's own adapters hold. */
+function clauseOf({ field, operator, value, mode }) {
+    const values = [value].flat();
+    const texts = mode === 'insensitive' && values.length && values.every((it) => typeof it === 'string') ? values : undefined;
+    return CLAUSES[operator](field, value, texts);
+}
+/** A literal case-insensitive match, which reads the same on every engine. */
+const ilike = (field, text) => ({ [field]: { $ilike: likeLiteral(text) } });
+/** An `in` list without `null`, which no `IN` matches and which makes every `NOT IN` match nothing. */
+const listOf = (value) => [value].flat().filter((it) => it !== null);
+/** Every Better Auth operator as the clause it is; `satisfies` fails the build on one it adds. */
+const CLAUSES = {
+    eq: (field, value, texts) => (texts ? ilike(field, texts[0]) : { [field]: { $eq: value } }),
+    ne: (field, value, texts) => (texts ? { $not: [ilike(field, texts[0])] } : { [field]: { $ne: value } }),
+    lt: (field, value) => ({ [field]: { $lt: value } }),
+    lte: (field, value) => ({ [field]: { $lte: value } }),
+    gt: (field, value) => ({ [field]: { $gt: value } }),
+    gte: (field, value) => ({ [field]: { $gte: value } }),
+    in: (field, value, texts) => texts ? { $or: texts.map((text) => ilike(field, text)) } : { [field]: { $in: listOf(value) } },
+    not_in: (field, value, texts) => texts ? { $nor: texts.map((text) => ilike(field, text)) } : { [field]: { $nin: listOf(value) } },
+    contains: (field, value, texts) => ({ [field]: { [texts ? '$iincludes' : '$includes']: value } }),
+    starts_with: (field, value, texts) => ({ [field]: { [texts ? '$istartsWith' : '$startsWith']: value } }),
+    ends_with: (field, value, texts) => ({ [field]: { [texts ? '$iendsWith' : '$endsWith']: value } }),
+};

package/dist/d1/d1SqliteDialect.js

@@ -7,7 +7,7 @@ import { UqlUsageError } from '../util/uqlError.js';
  */
 export class D1SqliteDialect extends SqliteDialect {
     /** A vector stays text: D1 answers a BLOB as an array of its byte values, which reads like a vector. */
-    features = { ...SQLITE_FEATURES, vectorBytes: false };
+    features = { ...SQLITE_FEATURES, vectorBytes: false, transactions: false };
     // Cloudflare D1 caps bound parameters at 100 per query.
     maxBindValues = 100;
     // And a function call at 32 arguments.

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -32,6 +32,7 @@ export const MYSQL_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: MYSQL_ROW_LOCKS,
+    transactions: true,
     nullsOrdering: 'expression',
     textScoreIndexes: true,
     orderedUpsertReturning: true,

package/dist/dialect/pgLikeSqlDialect.js

@@ -34,6 +34,7 @@ export const PG_FEATURES = {
     serverSideCursors: true,
     correlatedWrites: true,
     rowLocks: { of: true, withWindow: false, placement: 'suffix' },
+    transactions: true,
     nullsOrdering: 'clause',
     textScoreIndexes: false,
     orderedUpsertReturning: true,

package/dist/http/handler.d.ts

@@ -44,8 +44,11 @@ export type HookContext<E extends object, Ctx = unknown> = {
 export type Hook<Ctx = unknown> = <E extends object>(ctx: HookContext<E, Ctx>) => void | Promise<void>;
 export type ResponseHook<Ctx = unknown> = <E extends object>(ctx: HookContext<E, Ctx>, envelope: RequestSuccessResponse<unknown>) => void | Promise<void>;
 export type RequestHandlerOptions<Ctx = unknown> = {
-    include?: Type<object>[];
-    exclude?: Type<object>[];
+    /**
+     * The entities served, and the only ones a request reaches, through a relation too: nothing is served
+     * by being defined, so an entity holding secrets (a session's token) stays off the wire unless named.
+     */
+    include: readonly Type<object>[];
     /** The URL segment an entity is addressed by, its kebab-cased class name by default; the browser client takes the same option. */
     entityPath?: (entity: Type<unknown>) => string;
     /**

package/dist/http/handler.js

@@ -1,5 +1,5 @@
 import { withContext } from '../context/context.js';
-import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
+import { getMeta, soleIdOf } from '../entity/index.js';
 import { whereIds, whereWith } from '../util/dialect.util.js';
 import { UqlUsageError } from '../util/uqlError.js';
 import { CRUD_ROUTES, entityPath, matchRoute, } from './contract.js';
@@ -10,14 +10,11 @@ function tableOf(entity) {
     return `${entity.name} (${meta.schema ? `${meta.schema}.${meta.name}` : meta.name})`;
 }
 export function createRequestHandler(opts) {
-    const { include, exclude, pre, preSave, preFilter, post, getContext, pool } = opts;
+    const { include: entities, pre, preSave, preFilter, post, getContext, pool } = opts;
     const pathOf = opts.entityPath ?? entityPath;
-    let entities = include ?? getEntities();
-    if (exclude) {
-        entities = entities.filter((entity) => !exclude.includes(entity));
-    }
-    if (!entities.length) {
-        throw new UqlUsageError('no entities for the uql middleware');
+    // Refused rather than defaulted to every entity defined, which would serve whatever one registers.
+    if (!entities?.length) {
+        throw new UqlUsageError("name the entities the handler serves in 'include': it serves those alone");
     }
     // All of them at once, so fixing the first collision does not just reveal the next.
     const byPath = Map.groupBy(entities, pathOf);

package/dist/mongo/mongoDialect.js

@@ -32,6 +32,7 @@ export const mongoDialectFeatures = {
     serverSideCursors: false,
     correlatedWrites: false,
     rowLocks: false, // its concurrency control is the transaction plus atomic document updates
+    transactions: true,
 };
 /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
 const HEX_24 = /^[0-9a-f]{24}$/i;

package/dist/mssql/mssqlDialect.js

@@ -31,6 +31,7 @@ const MSSQL_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
+    transactions: true,
     nullsOrdering: 'case',
     textScoreIndexes: false,
     orderedUpsertReturning: false,

package/dist/sqlite/sqliteDialect.js

@@ -34,6 +34,7 @@ export const SQLITE_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: false,
+    transactions: true,
     nullsOrdering: 'clause',
     textScoreIndexes: false,
     orderedUpsertReturning: true,

package/dist/type/dialect.d.ts

@@ -141,6 +141,11 @@ export interface DialectFeatures {
      * value rather than a flag each, since the details mean nothing without a lock.
      */
     readonly rowLocks: RowLockFeatures | false;
+    /**
+     * Whether the engine runs a transaction across statements: false on D1, which refuses one, so what
+     * would open one can run its steps in order instead. MongoDB has them as a replica set alone.
+     */
+    readonly transactions: boolean;
 }
 /** How a dialect spells a row lock, once {@link DialectFeatures.rowLocks} says it has one. */
 export interface RowLockFeatures {

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -35,6 +35,7 @@
     "./http": "./dist/http/index.js",
     "./express": "./dist/express/index.js",
     "./nestjs": "./dist/nestjs/index.js",
+    "./betterAuth": "./dist/betterAuth/index.js",
     "./browser": {
       "types": "./dist/browser/index.d.ts",
       "import": "./dist/browser/index.js",
@@ -71,6 +72,7 @@
     "@nestjs/core": ">=10.0.0",
     "@tursodatabase/database": ">=0.7.0",
     "@tursodatabase/serverless": ">=1.3.0",
+    "better-auth": ">=1.7.0",
     "better-sqlite3": ">=9.0.0",
     "express": ">=5.0.0",
     "mariadb": ">=3.0.0",
@@ -103,6 +105,9 @@
     "@tursodatabase/serverless": {
       "optional": true
     },
+    "better-auth": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
     },
@@ -132,6 +137,7 @@
     }
   },
   "devDependencies": {
+    "@better-auth/test-utils": "^1.7.6",
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@libsql/client": "^0.18.0",
@@ -146,6 +152,7 @@
     "@types/mssql": "^12.3.0",
     "@types/pg": "^8.23.1",
     "@types/ws": "^8.18.1",
+    "better-auth": "^1.7.6",
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.4",

package/skills/uql-orm/SKILL.md

@@ -119,7 +119,8 @@ const users = await pool.findMany(User, {
 - A result is narrowed to what the query selected and populated: reading an unselected field is a compile error.
   Name that shape with `QueryFindResult<User, 'id' | 'email'>` rather than widening the query.
 - `$populate` loads relations in the same statement. Nothing is lazy: a relation not populated is not there.
-- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`.
+- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`,
+  whose handler serves only the entities its required `include` names.
 - Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyStream`, `count`, `exists`,
   `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`,
   `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first.
@@ -157,6 +158,13 @@ transaction. A querier from `pool.getQuerier()` is yours to release: bind it wit
 writes entity classes from an existing database; `drift:check` fails when the database no longer matches.
 Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names and never touches another.
 
+## Better Auth
+
+`betterAuth({ ...authOptions, database: uqlAdapter(pool) })`, from `uql-orm/betterAuth`, runs Better Auth on any
+pool; `...authEntities(authOptions)` in the config's `entities` has `uql-migrate` create its tables. Keep
+`authOptions` (plugins, table and field names, `rateLimit.storage`) in a module of its own, since the config imports
+it, and never put those entities in an HTTP handler's `include`: a session row holds its token.
+
 ## Where to read more
 
 - Operators, per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
@@ -165,4 +173,5 @@ Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names
 - Triggers: https://uql-orm.dev/entities/triggers.md
 - Every method's signature: https://uql-orm.dev/querying/methods.md
 - Coming from Prisma, Drizzle, TypeORM or MikroORM: https://uql-orm.dev/switching-to-uql.md
+- Better Auth: https://uql-orm.dev/better-auth.md
 - Breaking changes by version: https://uql-orm.dev/upgrade-guide.md