@atscript/moost-db 0.1.116 → 0.1.118

package/dist/db-space-registry-CKR6G-hi.d.mts

@@ -0,0 +1,27 @@
+import { DEFAULT_DB_SPACE as DEFAULT_DB_SPACE$1, DbSpace } from "@atscript/db";
+
+//#region src/db-space-registry.d.ts
+/**
+ * Registers a {@link DbSpace} for token-based controller binding
+ * (`@TableController(Model)`), keyed by `name` (defaults to
+ * {@link DEFAULT_DB_SPACE}).
+ *
+ * Call before `app.init()` — token resolution happens lazily when controllers
+ * are instantiated during init. Registering the same name twice replaces the
+ * previous space (used by tests).
+ *
+ * ```ts
+ * provideDbSpace(db)                    // "default"
+ * provideDbSpace(analyticsDb, "analytics")
+ * ```
+ */
+declare function provideDbSpace(space: DbSpace, name?: string): void;
+/**
+ * Returns the space registered under `name`, or throws with wiring guidance.
+ * Used by the token-form controller decorators; exported for advanced setups.
+ */
+declare function resolveDbSpace(name?: string): DbSpace;
+/** Removes all registered spaces. Intended for test teardown. */
+declare function clearDbSpaces(): void;
+//#endregion
+export { resolveDbSpace as i, clearDbSpaces as n, provideDbSpace as r, DEFAULT_DB_SPACE$1 as t };

package/dist/db-space-registry-CWpYwZ4R.d.cts

@@ -0,0 +1,27 @@
+import { DEFAULT_DB_SPACE, DbSpace } from "@atscript/db";
+
+//#region src/db-space-registry.d.ts
+/**
+ * Registers a {@link DbSpace} for token-based controller binding
+ * (`@TableController(Model)`), keyed by `name` (defaults to
+ * {@link DEFAULT_DB_SPACE}).
+ *
+ * Call before `app.init()` — token resolution happens lazily when controllers
+ * are instantiated during init. Registering the same name twice replaces the
+ * previous space (used by tests).
+ *
+ * ```ts
+ * provideDbSpace(db)                    // "default"
+ * provideDbSpace(analyticsDb, "analytics")
+ * ```
+ */
+declare function provideDbSpace(space: DbSpace, name?: string): void;
+/**
+ * Returns the space registered under `name`, or throws with wiring guidance.
+ * Used by the token-form controller decorators; exported for advanced setups.
+ */
+declare function resolveDbSpace(name?: string): DbSpace;
+/** Removes all registered spaces. Intended for test teardown. */
+declare function clearDbSpaces(): void;
+//#endregion
+export { resolveDbSpace as i, clearDbSpaces as n, provideDbSpace as r, DEFAULT_DB_SPACE as t };

package/dist/db-space-registry-C_wft7kl.mjs

@@ -0,0 +1,48 @@
+import { DEFAULT_DB_SPACE, DEFAULT_DB_SPACE as DEFAULT_DB_SPACE$1 } from "@atscript/db";
+//#region src/db-space-registry.ts
+/**
+* Ambient registry of {@link DbSpace} instances, keyed by name.
+*
+* WHY module-level and not Moost DI: provide factories in the DI container
+* take no arguments (they cannot resolve sibling tokens), and controllers that
+* declare their own constructors never execute the base class's `@Inject`
+* decorations — so a DI-carried space would silently miss both paths. The
+* ambient registry works for every binding form and can be superseded by a
+* DI-native path later without breaking this API.
+*/
+const spaces = /* @__PURE__ */ new Map();
+/**
+* Registers a {@link DbSpace} for token-based controller binding
+* (`@TableController(Model)`), keyed by `name` (defaults to
+* {@link DEFAULT_DB_SPACE}).
+*
+* Call before `app.init()` — token resolution happens lazily when controllers
+* are instantiated during init. Registering the same name twice replaces the
+* previous space (used by tests).
+*
+* ```ts
+* provideDbSpace(db)                    // "default"
+* provideDbSpace(analyticsDb, "analytics")
+* ```
+*/
+function provideDbSpace(space, name = DEFAULT_DB_SPACE) {
+	spaces.set(name, space);
+}
+/**
+* Returns the space registered under `name`, or throws with wiring guidance.
+* Used by the token-form controller decorators; exported for advanced setups.
+*/
+function resolveDbSpace(name = DEFAULT_DB_SPACE) {
+	const space = spaces.get(name);
+	if (!space) {
+		const known = [...spaces.keys()];
+		throw new Error(`[moost-db] No DbSpace registered under "${name}". Call provideDbSpace(space${name === DEFAULT_DB_SPACE ? "" : `, "${name}"`}) before app.init(). ` + (known.length ? `Registered spaces: ${known.join(", ")}.` : "No spaces registered yet."));
+	}
+	return space;
+}
+/** Removes all registered spaces. Intended for test teardown. */
+function clearDbSpaces() {
+	spaces.clear();
+}
+//#endregion
+export { resolveDbSpace as i, clearDbSpaces as n, provideDbSpace as r, DEFAULT_DB_SPACE$1 as t };

package/dist/db-space-registry-DqKr5Zdk.cjs

@@ -0,0 +1,65 @@
+let _atscript_db = require("@atscript/db");
+//#region src/db-space-registry.ts
+/**
+* Ambient registry of {@link DbSpace} instances, keyed by name.
+*
+* WHY module-level and not Moost DI: provide factories in the DI container
+* take no arguments (they cannot resolve sibling tokens), and controllers that
+* declare their own constructors never execute the base class's `@Inject`
+* decorations — so a DI-carried space would silently miss both paths. The
+* ambient registry works for every binding form and can be superseded by a
+* DI-native path later without breaking this API.
+*/
+const spaces = /* @__PURE__ */ new Map();
+/**
+* Registers a {@link DbSpace} for token-based controller binding
+* (`@TableController(Model)`), keyed by `name` (defaults to
+* {@link DEFAULT_DB_SPACE}).
+*
+* Call before `app.init()` — token resolution happens lazily when controllers
+* are instantiated during init. Registering the same name twice replaces the
+* previous space (used by tests).
+*
+* ```ts
+* provideDbSpace(db)                    // "default"
+* provideDbSpace(analyticsDb, "analytics")
+* ```
+*/
+function provideDbSpace(space, name = _atscript_db.DEFAULT_DB_SPACE) {
+	spaces.set(name, space);
+}
+/**
+* Returns the space registered under `name`, or throws with wiring guidance.
+* Used by the token-form controller decorators; exported for advanced setups.
+*/
+function resolveDbSpace(name = _atscript_db.DEFAULT_DB_SPACE) {
+	const space = spaces.get(name);
+	if (!space) {
+		const known = [...spaces.keys()];
+		throw new Error(`[moost-db] No DbSpace registered under "${name}". Call provideDbSpace(space${name === _atscript_db.DEFAULT_DB_SPACE ? "" : `, "${name}"`}) before app.init(). ` + (known.length ? `Registered spaces: ${known.join(", ")}.` : "No spaces registered yet."));
+	}
+	return space;
+}
+/** Removes all registered spaces. Intended for test teardown. */
+function clearDbSpaces() {
+	spaces.clear();
+}
+//#endregion
+Object.defineProperty(exports, "clearDbSpaces", {
+	enumerable: true,
+	get: function() {
+		return clearDbSpaces;
+	}
+});
+Object.defineProperty(exports, "provideDbSpace", {
+	enumerable: true,
+	get: function() {
+		return provideDbSpace;
+	}
+});
+Object.defineProperty(exports, "resolveDbSpace", {
+	enumerable: true,
+	get: function() {
+		return resolveDbSpace;
+	}
+});

package/dist/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_db_space_registry = require("./db-space-registry-DqKr5Zdk.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _moostjs_event_http = require("@moostjs/event-http");
 let moost = require("moost");
@@ -913,57 +914,140 @@ const READABLE_DEF = "__atscript_db_readable_def";
 * Points to the same token as READABLE_DEF for backward compatibility.
 */
 const TABLE_DEF = READABLE_DEF;
+function normalizeOptions(prefixOrOptions) {
+	if (typeof prefixOrOptions === "string") return { prefix: prefixOrOptions };
+	return prefixOrOptions ?? {};
+}
+/**
+* Builds the shared binding metadata for a decorator invocation: classifies
+* the binding form, computes the static route prefix, and packages a uniform
+* `resolve()` used by both the DI provide factory and the base controller's
+* `super(undefined, app)` fallback.
+*/
+function buildBinding(binding, options, decoratorName) {
+	if ((0, _atscript_typescript_utils.isAnnotatedType)(binding)) {
+		const model = binding;
+		const space = options.space ?? model.metadata.get("db.space");
+		const prefix = options.prefix || model.metadata.get("db.http.path") || model.metadata.get("db.table") || model.metadata.get("db.view") || model.id || "";
+		if (!prefix) throw new Error(`[moost-db] @${decoratorName}: cannot derive a route prefix from the model token (no @db.http.path / @db.table / @db.view and no type id). Pass an explicit prefix.`);
+		return {
+			meta: {
+				model,
+				resolve: () => require_db_space_registry.resolveDbSpace(space).get(model)
+			},
+			prefix
+		};
+	}
+	if (typeof binding === "function") {
+		if (!options.prefix) throw new Error(`[moost-db] @${decoratorName}: the lazy factory form needs an explicit route prefix (the readable is not created until app.init()). Pass a prefix, or use the model token form which derives it from @db.http.path / @db.table.`);
+		return {
+			meta: { resolve: binding },
+			prefix: options.prefix
+		};
+	}
+	const readable = binding;
+	const prefix = options.prefix || readable.type.metadata.get("db.http.path") || readable.tableName;
+	return {
+		meta: {
+			model: readable.type,
+			resolve: () => readable
+		},
+		prefix
+	};
+}
+function bindReadableController(binding, prefixOrOptions, decoratorName) {
+	const { meta, prefix } = buildBinding(binding, normalizeOptions(prefixOrOptions), decoratorName);
+	return (0, moost.ApplyDecorators)(getAtscriptDbMate().decorate((classMeta) => {
+		classMeta.atscript_db_readable_binding = meta;
+		return classMeta;
+	}), (0, moost.Provide)(READABLE_DEF, () => meta.resolve()), (0, moost.Controller)(prefix), (0, moost.Inherit)());
+}
 /**
 * Combines the boilerplate needed to turn an {@link AsDbController}
 * subclass into a fully wired HTTP controller for a given `@db.table` model.
 *
 * Internally applies three decorators:
-* 1. **Provide** — registers the table instance under {@link TABLE_DEF}.
+* 1. **Provide** — registers the readable resolver under {@link TABLE_DEF}.
 * 2. **Controller** — registers the class as a Moost HTTP controller
-*    with an optional route prefix. Defaults to `table.tableName`.
+*    with an optional route prefix (defaults to `@db.http.path`, then the
+*    table name).
 * 3. **Inherit** — copies metadata (routes, guards, etc.) from the
 *    parent class so they stay active in the derived controller.
 *
-* @param table  The {@link AtscriptDbTable} instance for this controller.
-* @param prefix Optional route prefix. Defaults to `table.tableName`.
+* All three binding forms are supported (see {@link TReadableBinding}):
 *
-* @example
 * ```ts
-* ‎@TableController(usersTable)
-* export class UsersController extends AsDbController<typeof UserModel> {}
+* ‎@TableController(User)                      // model token (preferred)
+* ‎@TableController(User, { space: "analytics" })
+* ‎@TableController(() => db.getTable(User), "users") // lazy factory
+* ‎@TableController(usersTable)                // instance (legacy)
+* export class UsersController extends AsDbController<typeof User> {}
 * ```
+*
+* Token and factory forms resolve lazily at first controller instantiation
+* (during `app.init()`), so the `DbSpace` does not have to exist when the
+* controller module is imported. For the token form, register the space with
+* `provideDbSpace(db)` before `app.init()`.
+*
+* @param binding Model token, lazy factory, or {@link AtscriptDbTable} instance.
+* @param prefixOrOptions Route prefix string, or {@link TControllerBindingOptions}.
 */
-const TableController = (table, prefix) => {
-	const resolvedPath = prefix || table.type.metadata.get("db.http.path");
-	return (0, moost.ApplyDecorators)((0, moost.Provide)(TABLE_DEF, () => table), (0, moost.Controller)(resolvedPath || table.tableName), (0, moost.Inherit)());
-};
+const TableController = (binding, prefixOrOptions) => bindReadableController(binding, prefixOrOptions, "TableController");
 /**
 * Combines the boilerplate needed to turn an {@link AsDbReadableController}
 * subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
 *
-* @param readable  The {@link AtscriptDbReadable} instance (table or view).
-* @param prefix    Optional route prefix. Defaults to `readable.tableName`.
+* Accepts the same three binding forms as {@link TableController}.
+*
+* @param binding Model token, lazy factory, or {@link AtscriptDbReadable} instance.
+* @param prefixOrOptions Route prefix string, or {@link TControllerBindingOptions}.
 *
 * @example
 * ```ts
-* ‎@ReadableController(activeTasksView)
+* ‎@ReadableController(ActiveTasks)
 * export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
 * ```
 */
-const ReadableController = (readable, prefix) => {
-	const resolvedPath = prefix || readable.type.metadata.get("db.http.path");
-	return (0, moost.ApplyDecorators)((0, moost.Provide)(READABLE_DEF, () => readable), (0, moost.Controller)(resolvedPath || readable.tableName), (0, moost.Inherit)());
-};
+const ReadableController = (binding, prefixOrOptions) => bindReadableController(binding, prefixOrOptions, "ReadableController");
 /**
 * Alias for {@link ReadableController} — use with view-backed controllers.
 *
 * @example
 * ```ts
-* ‎@ViewController(activeTasksView)
+* ‎@ViewController(ActiveTasks)
 * export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
 * ```
 */
 const ViewController = ReadableController;
+/**
+* Finds the readable binding written by `@TableController` /
+* `@ReadableController` / `@ViewController` on a controller class, walking the
+* prototype chain so intermediate undecorated classes don't hide the binding
+* (nearest decorated ancestor wins).
+*/
+function findReadableBinding(ctor) {
+	const mate = getAtscriptDbMate();
+	let current = ctor;
+	while (typeof current === "function") {
+		const binding = mate.read(current)?.atscript_db_readable_binding;
+		if (binding) return binding;
+		current = Object.getPrototypeOf(current);
+	}
+}
+/**
+* Resolves the readable bound to a controller class via
+* {@link findReadableBinding}, throwing with wiring guidance when none is
+* found.
+*
+* Used by {@link AsDbReadableController}'s constructor when `readable` is
+* `undefined` — i.e. a subclass with its own constructor called
+* `super(undefined, app)` instead of forwarding an injected instance.
+*/
+function resolveBoundReadable(ctor) {
+	const binding = findReadableBinding(ctor);
+	if (binding) return binding.resolve();
+	throw new Error(`[moost-db] ${ctor?.name || "controller"}: no readable bound. Either pass a table/view to super(...), or decorate the class with @TableController / @ReadableController (model token, lazy factory, or instance form).`);
+}
 //#endregion
 //#region src/permissions/crud-controls.ts
 /**
@@ -1013,11 +1097,12 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
 	_adapterNonFilterable;
 	constructor(readable, app) {
-		super(readable.type, readable.tableName, app, readable.isView ? "view" : "table");
-		this.readable = readable;
+		const resolved = readable ?? resolveBoundReadable(new.target);
+		super(resolved.type, resolved.tableName, app, resolved.isView ? "view" : "table");
+		this.readable = resolved;
 		this._adapterNonFilterable = this._collectAdapterNonFilterable();
 		this._gates = this._buildGates();
-		this._preferredIdSet = new Set(readable.preferredId ?? []);
+		this._preferredIdSet = new Set(resolved.preferredId ?? []);
 		this._quantityRefByPath = this._collectQuantityRefs();
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
@@ -1674,6 +1759,7 @@ __decorate([
 AsDbReadableController = __decorate([
 	(0, moost.Inherit)(),
 	__decorateParam(0, (0, moost.Inject)(READABLE_DEF)),
+	__decorateParam(0, (0, moost.Optional)()),
 	__decorateMetadata("design:paramtypes", [Object, typeof moost.Moost === "undefined" ? Object : moost.Moost])
 ], AsDbReadableController);
 registerAsDbReadableController(AsDbReadableController);
@@ -1871,6 +1957,7 @@ __decorate([
 AsDbController = __decorate([
 	(0, moost.Inherit)(),
 	__decorateParam(0, (0, moost.Inject)(TABLE_DEF)),
+	__decorateParam(0, (0, moost.Optional)()),
 	__decorateMetadata("design:paramtypes", [Object, typeof moost.Moost === "undefined" ? Object : moost.Moost])
 ], AsDbController);
 //#endregion
@@ -2139,6 +2226,44 @@ AsJsonValueHelpController = __decorate([(0, moost.Inherit)(), __decorateMetadata
 	String
 ])], AsJsonValueHelpController);
 //#endregion
+//#region src/assert-exposed.ts
+/**
+* Dev-mode wiring assertion: warns for every model annotated with
+* `@db.http.path` that has no registered db controller.
+*
+* Call AFTER `await app.init()` (controller bindings are collected during
+* init). Detection reads the binding metadata written by `@TableController` /
+* `@ReadableController` / `@ViewController`, so it covers the model-token and
+* instance forms; lazy-factory bindings can't name their model until resolved
+* and are ignored.
+*
+* Returns the list of unexposed models so callers can escalate (e.g. throw in
+* CI):
+*
+* ```ts
+* await app.init()
+* const missing = assertExposed(app, atscriptModels)
+* if (missing.length && process.env.CI) throw new Error("unexposed models")
+* ```
+*/
+function assertExposed(app, models, options) {
+	const logger = options?.logger ?? console;
+	const exposed = /* @__PURE__ */ new Set();
+	for (const overview of app.getControllersOverview()) {
+		const model = findReadableBinding(overview.type)?.model;
+		if (model) exposed.add(model);
+	}
+	const missing = [];
+	for (const model of models) {
+		if (!model.metadata.has("db.http.path")) continue;
+		if (exposed.has(model)) continue;
+		missing.push(model);
+		const path = model.metadata.get("db.http.path");
+		logger.warn(`[moost-db] Model "${model.id ?? path}" declares @db.http.path "${path}" but no registered controller is bound to it. Did you forget to register its controller?`);
+	}
+	return missing;
+}
+//#endregion
 //#region src/actions/action-disabled-error.ts
 function buildMessage(action, ids) {
 	if (ids !== void 0) return `Action "${action}" is disabled for ${ids.length} of the selected rows`;
@@ -2759,6 +2884,12 @@ Object.defineProperty(exports, "AsValueHelpController", {
 		return AsValueHelpController;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_DB_SPACE", {
+	enumerable: true,
+	get: function() {
+		return _atscript_db.DEFAULT_DB_SPACE;
+	}
+});
 exports.DbAction = DbAction;
 exports.DbActionDefault = DbActionDefault;
 exports.DbActionID = DbActionID;
@@ -2779,12 +2910,18 @@ exports.TABLE_DEF = TABLE_DEF;
 exports.TableController = TableController;
 exports.UseValidationErrorTransform = UseValidationErrorTransform;
 exports.ViewController = ViewController;
+exports.assertExposed = assertExposed;
+exports.clearDbSpaces = require_db_space_registry.clearDbSpaces;
 exports.dbActionBodySlot = dbActionBodySlot;
 exports.dbActionInputSlot = dbActionInputSlot;
 exports.discoverActions = discoverActions;
+exports.findReadableBinding = findReadableBinding;
 exports.getAtscriptDbMate = getAtscriptDbMate;
 exports.getControllerFormType = getControllerFormType;
 exports.perRow = perRow;
+exports.provideDbSpace = require_db_space_registry.provideDbSpace;
+exports.resolveBoundReadable = resolveBoundReadable;
+exports.resolveDbSpace = require_db_space_registry.resolveDbSpace;
 exports.useDbActionId = useDbActionId;
 exports.useDbActionIds = useDbActionIds;
 exports.useDbActionInput = useDbActionInput;