@fabrika/db 0.0.0-stage → 0.4.0

package/src/production.ts

@@ -0,0 +1,26 @@
+// @fabrika/db/production — whether this process serves an application. The generated entrypoint marks it before it
+// imports the application, and the test kits refuse to load or run once it is marked. The mark is one non-writable,
+// non-configurable property of `globalThis` under a registered symbol, so every installed copy of this package reads
+// the same mark, it survives the scrub of the framework's variables (`FABRIKA_RELEASE` included), and nothing unmarks
+// it. Browser- and Worker-safe.
+
+const PRODUCTION = Symbol.for('fabrika.production')
+
+/** Marks this process as one that serves an application; called by the generated entrypoint only. */
+export function markProductionProcess(): void {
+	if (isProductionProcess()) {
+		return
+	}
+	Object.defineProperty(globalThis, PRODUCTION, { value: true, writable: false, configurable: false, enumerable: false })
+}
+
+export function isProductionProcess(): boolean {
+	return Reflect.get(globalThis, PRODUCTION) === true
+}
+
+/** Throws when this process serves an application: `what` is a test helper, which production never runs. */
+export function refuseInProduction(what: string): void {
+	if (isProductionProcess()) {
+		throw new Error(`${what} is a test helper; this process serves an application, so it neither loads nor runs here`)
+	}
+}

package/src/registry.ts

@@ -0,0 +1,57 @@
+// Which objects `scoped` created, and the framework side of each. Module-private state: the only readers are
+// `store.ts`, which registers and builds the framework's stores, `framework.ts`, which `@fabrika/app` alone imports, and `testing.ts`, which only test
+// files may import.
+
+import type { FileTables } from './file-tables'
+import type { FormAdmissions, InboxQuota } from './form-admissions'
+import type { WebhookTables } from './framework-tables'
+import type { JobLeases } from './job-leases'
+import type { DataAccess } from './orm'
+import type { DataLayerRuntime, TableContext, TableProbe } from './store'
+
+/** Answers what the framework's access check reads from the database: an object's containers, by dimension. */
+export type Locator = (dimension: string, id: string) => Promise<ReadonlyMap<string, string> | null>
+
+/** What the framework writes itself: a form's inbox row and its own `fabrika_*` tables. Usable once bound. */
+export interface FrameworkTables {
+	/** Why `fields` of form `form` cannot be appended to an inbox table of this layer; empty when they can. */
+	inboxProblems(form: string, fields: readonly string[]): readonly string[]
+	/**
+	 * Appends one row of `values` (column → value) to the inbox table of `form`, taking one from `quota` in the same
+	 * transaction; `false`, with nothing written, when the bucket is full.
+	 */
+	appendToInbox(form: string, values: Readonly<Record<string, unknown>>, quota: InboxQuota): Promise<boolean>
+	readonly webhooks: WebhookTables
+	readonly jobs: JobLeases
+	/** A form's admission counters and the challenge tokens it accepted. */
+	readonly forms: FormAdmissions
+}
+
+export interface FrameworkSide {
+	/** Connects the layer once and answers its locator; a second call throws. */
+	bind(runtime: DataLayerRuntime): Locator
+	/** The rows of the file collections' tables; usable once bound. */
+	readonly files: FileTables
+	readonly framework: FrameworkTables
+	/** The untyped handle over one table that `@fabrika/db/testing` hands the isolation tests. */
+	probe(table: string): TableProbe
+	/** One table's context, for the framework's own store builders (`defineStore`, `@fabrika/db/testing`). */
+	tableContext(table: string, mode: 'dimension' | 'child'): TableContext
+	/** The mini-ORM: invocation transactions and the handles of `ctx.db`; usable once bound. */
+	readonly data: DataAccess
+}
+
+// Captured when the module loads, before application code: a later patch to WeakMap does not change the registry.
+const registry = new WeakMap<object, FrameworkSide>()
+const weakGet: (this: WeakMap<object, FrameworkSide>, key: object) => FrameworkSide | undefined = WeakMap.prototype.get
+const weakSet: (this: WeakMap<object, FrameworkSide>, key: object, value: FrameworkSide) => WeakMap<object, FrameworkSide> = WeakMap.prototype.set
+const apply = Reflect.apply
+
+export function register(database: object, side: FrameworkSide): void {
+	apply(weakSet, registry, [database, side])
+}
+
+/** The framework side of an object `scoped` created; undefined for anything else, a structural copy included. */
+export function frameworkSideOf(value: unknown): FrameworkSide | undefined {
+	return typeof value === 'object' && value !== null ? apply(weakGet, registry, [value]) : undefined
+}