@c9up/atlas 0.1.3

package/src/decorators/scope.ts

@@ -0,0 +1,44 @@
+/**
+ * `scope()` — typed identity helper for declaring entity query scopes.
+ *
+ * Entity classes expose reusable filter/sort logic via `static scopes = {...}`.
+ * TypeScript can't infer the scope type on the naked object form, so this
+ * helper lets callers pin the argument types explicitly:
+ *
+ *     class User extends BaseEntity {
+ *       static scopes = {
+ *         active:  scope((q: ModelQuery<User>) => q.where('status', 'active')),
+ *         forOrg:  scope((q: ModelQuery<User>, org: Org) => q.where('org_id', org.id)),
+ *       }
+ *     }
+ *
+ * The runtime is an identity pass-through — `scope` returns its argument
+ * unchanged. Its only purpose is to give TS enough information to infer the
+ * scope's parameter types (and, by extension, the return type of
+ * `repo.query().apply(s => s.forOrg(...))` call sites).
+ *
+ * @implements Story 29.8 (scope helper)
+ */
+
+import type { BaseEntity } from "../BaseEntity.js";
+import type { ModelQuery } from "../ModelQuery.js";
+
+/**
+ * A query scope function — takes the current query as first argument and
+ * an arbitrary list of extra arguments. Returns the query for chaining
+ * (or `void` — the chain is applied in place).
+ */
+export type ScopeFn<TEntity extends BaseEntity, Args extends unknown[] = []> = (
+	query: ModelQuery<TEntity>,
+	...args: Args
+) => ModelQuery<TEntity> | undefined;
+
+/**
+ * Typed identity helper. Pass any scope function through `scope()` to get
+ * TS inference without changing the runtime behaviour.
+ */
+export function scope<TEntity extends BaseEntity, Args extends unknown[] = []>(
+	fn: ScopeFn<TEntity, Args>,
+): ScopeFn<TEntity, Args> {
+	return fn;
+}

package/src/errors.ts

@@ -0,0 +1,111 @@
+/**
+ * Atlas error hierarchy — structured errors for the ORM layer.
+ *
+ * Every error extends {@link AtlasError} with a stable code (prefixed `ATLAS_`),
+ * a human-readable message, and an optional hint. Specialised subclasses allow
+ * callers to catch by type (`catch (e) { if (e instanceof OptimisticLockError) ... }`)
+ * without string-matching on codes.
+ *
+ * @implements Story 32.10
+ */
+
+export class AtlasError extends Error {
+	readonly code: string;
+	readonly hint?: string;
+
+	constructor(code: string, message: string, options?: { hint?: string }) {
+		super(message);
+		this.name = "AtlasError";
+		this.code = code.startsWith("ATLAS_") ? code : `ATLAS_${code}`;
+		this.hint = options?.hint;
+	}
+}
+
+/**
+ * Thrown when an entity cannot be found (find, findOrFail, firstOrFail).
+ */
+export class EntityNotFoundError extends AtlasError {
+	readonly entityClass: string;
+	readonly criteria: unknown;
+
+	constructor(entityClass: string, criteria: unknown, hint?: string) {
+		super(
+			"E_ENTITY_NOT_FOUND",
+			`${entityClass} not found with ${JSON.stringify(criteria)}`,
+			{ hint },
+		);
+		this.name = "EntityNotFoundError";
+		this.entityClass = entityClass;
+		this.criteria = criteria;
+	}
+}
+
+/**
+ * Thrown when an optimistic lock check fails on save — the row was modified
+ * by another transaction since we read it. Requires `@Version()` column on the entity.
+ */
+export class OptimisticLockError extends AtlasError {
+	readonly entityClass: string;
+	readonly primaryKey: unknown;
+	readonly expectedVersion: number;
+
+	constructor(
+		entityClass: string,
+		primaryKey: unknown,
+		expectedVersion: number,
+	) {
+		super(
+			"E_OPTIMISTIC_LOCK",
+			`Optimistic lock failure saving ${entityClass}#${String(primaryKey)}: the row was modified by another transaction (expected version ${expectedVersion}).`,
+			{ hint: "Reload the entity, reapply your changes, and try again." },
+		);
+		this.name = "OptimisticLockError";
+		this.entityClass = entityClass;
+		this.primaryKey = primaryKey;
+		this.expectedVersion = expectedVersion;
+	}
+}
+
+/**
+ * Thrown when accessing a relation that was not eager-loaded AND has no lazy
+ * loader available on the entity. Forces callers to be explicit about loading.
+ */
+export class RelationNotLoadedError extends AtlasError {
+	readonly entityClass: string;
+	readonly relationName: string;
+
+	constructor(entityClass: string, relationName: string) {
+		super(
+			"E_RELATION_NOT_LOADED",
+			`Relation '${relationName}' on ${entityClass} was not loaded.`,
+			{
+				hint: `Call .preload('${relationName}') on the query or .load('${relationName}') on the instance.`,
+			},
+		);
+		this.name = "RelationNotLoadedError";
+		this.entityClass = entityClass;
+		this.relationName = relationName;
+	}
+}
+
+/**
+ * Thrown when mass-assignment (`fill` / `merge` / `create`) tries to set a
+ * field that is not in the `fillable` list or is in the `guarded` list.
+ */
+export class MassAssignmentError extends AtlasError {
+	readonly entityClass: string;
+	readonly attribute: string;
+
+	constructor(entityClass: string, attribute: string) {
+		super(
+			"E_MASS_ASSIGNMENT",
+			`Attribute '${attribute}' on ${entityClass} is not mass-assignable.`,
+			{
+				hint: `Add '${attribute}' to the static 'fillable' array or remove it from 'guarded'.`,
+			},
+		);
+		this.name = "MassAssignmentError";
+		this.entityClass = entityClass;
+		this.attribute = attribute;
+	}
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * @module @c9up/atlas
+ * @description Atlas — Data Mapper ORM for the Ream framework
+ * @implements FR29, FR30, FR31, FR34, FR35, FR37
+ */
+
+import "reflect-metadata";
+
+export { SQLITE_PROD_PRAGMAS } from "./AtlasProvider.js";
+export type { AsyncDatabaseConnection } from "./adapters/NapiDbAdapter.js";
+export { createNapiConnection } from "./adapters/NapiDbAdapter.js";
+export type { DomainEvent } from "./BaseEntity.js";
+export { BaseEntity } from "./BaseEntity.js";
+export type { DatabaseConnection } from "./BaseRepository.js";
+export { BaseRepository } from "./BaseRepository.js";
+export { defineConfig } from "./config.js";
+export { configure } from "./configure.js";
+export type {
+	ColumnAdapter,
+	ColumnMetadata,
+	ColumnOptions,
+	DateColumnConfig,
+	DateTimeColumnOptions,
+	EntityMetadata,
+	ManyToManyOptions,
+	RelationMetadata,
+} from "./decorators/entity.js";
+export {
+	BelongsTo,
+	Column,
+	column,
+	computed,
+	Entity,
+	getColumnMetadata,
+	getDateColumnConfig,
+	getEntityMetadata,
+	getPrimaryKey,
+	getRelationMetadata,
+	HasMany,
+	HasManyThrough,
+	HasOne,
+	HasOneThrough,
+	hasSoftDeletes,
+	ManyToMany,
+	PrimaryKey,
+	SoftDeletes,
+} from "./decorators/entity.js";
+export {
+	afterCreate,
+	afterDelete,
+	afterFetch,
+	afterFind,
+	afterPaginate,
+	afterSave,
+	afterUpdate,
+	beforeCreate,
+	beforeDelete,
+	beforeFetch,
+	beforeFind,
+	beforePaginate,
+	beforeSave,
+	beforeUpdate,
+} from "./decorators/hooks.js";
+export type { ScopeFn } from "./decorators/scope.js";
+export { scope } from "./decorators/scope.js";
+export {
+	AtlasError,
+	EntityNotFoundError,
+	MassAssignmentError,
+	OptimisticLockError,
+	RelationNotLoadedError,
+} from "./errors.js";
+export {
+	isAtlasStrictMode,
+	ModelQuery,
+	setAtlasStrictMode,
+} from "./ModelQuery.js";
+export type { NamingStrategy } from "./naming/NamingStrategy.js";
+export {
+	CamelCaseNamingStrategy,
+	defaultNamingStrategy,
+	getNamingStrategy,
+} from "./naming/NamingStrategy.js";
+export type { AtlasDialect } from "./query/native.js";
+export { getAtlasDialect, setAtlasDialect } from "./query/native.js";
+export type {
+	CteDefinition,
+	ExistsClause,
+	OrderByClause,
+	QueryResult,
+	WhereClause,
+	WhereOperator,
+} from "./query/QueryBuilder.js";
+export { QueryBuilder, RawSql } from "./query/QueryBuilder.js";
+export { Migration } from "./schema/Migration.js";
+export type {
+	DatabaseAdapter,
+	MigrationRecord,
+	MigrationState,
+	MigrationStatus,
+} from "./schema/MigrationRunner.js";
+export { MigrationRunner } from "./schema/MigrationRunner.js";
+export type { ColumnDefinition, ColumnType } from "./schema/SchemaBuilder.js";
+export { Schema, TableBuilder } from "./schema/SchemaBuilder.js";
+export {
+	BaseSeeder,
+	runSeederDirectory,
+	runSeeders,
+	Seeder,
+} from "./schema/Seeder.js";
+export type { TransactionClient } from "./Transaction.js";
+export { transaction } from "./Transaction.js";
+export { truncateAll, useTransaction } from "./testing/DatabaseCleanup.js";
+export { factory } from "./testing/Factory.js";

package/src/naming/NamingStrategy.ts

@@ -0,0 +1,106 @@
+/**
+ * Naming Strategy — override the snake_case ↔ camelCase convention per-entity.
+ *
+ * Each entity class can declare `static namingStrategy = new MyStrategy()` to
+ * replace the default camelCase ↔ snake_case conversion with its own rules.
+ * Used to migrate legacy databases (e.g. PascalCase columns, prefixed tables,
+ * custom pivot table names).
+ *
+ *     class LegacyUser extends BaseEntity {
+ *       static namingStrategy = new SnakeCaseSingularStrategy()
+ *     }
+ *
+ * @implements Story 32.7
+ */
+
+import { camelToSnake, snakeToCamel } from "../utils/casing.js";
+
+/** Constructor-level hook for a naming override. Defaults to camelCase ↔ snake_case. */
+export interface NamingStrategy {
+	/** Table name for an entity class, given its constructor name. */
+	tableName(className: string): string;
+	/** Database column name for a TS property (e.g. `userId` → `user_id`). */
+	columnName(propertyName: string): string;
+	/** Reverse mapping — DB column back to the TS property. Used by hydrate. */
+	propertyName(columnName: string): string;
+	/** Serialized field name in `toJSON()`. Defaults to the property name. */
+	serializedName(propertyName: string): string;
+	/** Local key for a belongsTo/hasMany relation (usually the parent PK). */
+	relationLocalKey(
+		kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
+		parentPk: string,
+	): string;
+	/** Foreign key column name on the owning side of a relation. */
+	relationForeignKey(
+		kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
+		parentClass: string,
+		parentPk: string,
+	): string;
+	/** Default pivot table name for a manyToMany relation. */
+	relationPivotTable(aClass: string, bClass: string): string;
+}
+
+/**
+ * Default strategy — camelCase TS properties, snake_case DB columns, plural
+ * snake_case table names, `<parent_name>_<parent_pk>` foreign keys.
+ */
+export class CamelCaseNamingStrategy implements NamingStrategy {
+	tableName(className: string): string {
+		// Default: snake_case + plural-s. Entities wanting non-default (e.g. irregular
+		// plurals like "people") should override via static `namingStrategy`.
+		const snake = camelToSnake(className);
+		return snake.endsWith("s") ? snake : `${snake}s`;
+	}
+
+	columnName(propertyName: string): string {
+		return camelToSnake(propertyName);
+	}
+
+	propertyName(columnName: string): string {
+		return snakeToCamel(columnName);
+	}
+
+	serializedName(propertyName: string): string {
+		return propertyName;
+	}
+
+	relationLocalKey(
+		_kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
+		parentPk: string,
+	): string {
+		return parentPk;
+	}
+
+	relationForeignKey(
+		_kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
+		parentClass: string,
+		parentPk: string,
+	): string {
+		return `${camelToSnake(parentClass)}_${parentPk}`;
+	}
+
+	relationPivotTable(aClass: string, bClass: string): string {
+		// Sort alphabetically so `UserSkill` and `SkillUser` collapse to the same name.
+		const [x, y] = [camelToSnake(aClass), camelToSnake(bClass)].sort();
+		return `${x}_${y}`;
+	}
+}
+
+/** The default singleton — used when an entity doesn't override `static namingStrategy`. */
+export const defaultNamingStrategy: NamingStrategy =
+	new CamelCaseNamingStrategy();
+
+/**
+ * Resolve the naming strategy for an entity class. Walks the prototype chain
+ * so subclasses inherit their parent's strategy unless they override.
+ */
+export function getNamingStrategy(entityClass: object): NamingStrategy {
+	let current: object | null = entityClass;
+	while (current && current !== Function.prototype) {
+		const explicit = (current as { namingStrategy?: NamingStrategy })
+			.namingStrategy;
+		if (explicit) return explicit;
+		current = Object.getPrototypeOf(current);
+	}
+	return defaultNamingStrategy;
+}