@meridianjs/framework-utils 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,132 @@
+# @meridianjs/framework-utils
+
+Core building blocks for creating MeridianJS modules: the DML (Data Modelling Language), the `MeridianService` factory, `Module()`, `defineLink()`, and ORM utilities.
+
+## Installation
+
+```bash
+npm install @meridianjs/framework-utils
+```
+
+## Overview
+
+Every domain module in a MeridianJS application is built with the primitives this package exports. You define your data models with `model`, generate CRUD services with `MeridianService`, wire up a module with `Module()`, and declare cross-module relationships with `defineLink()`.
+
+## API Reference
+
+### `model` — Data Modelling Language
+
+Define a database entity without writing MikroORM decorators:
+
+```typescript
+import { model } from "@meridianjs/framework-utils"
+
+export const Project = model("project", {
+  id:          model.id(),            // UUID primary key, auto-generated
+  name:        model.text(),          // VARCHAR
+  description: model.text(),
+  color:       model.text(),
+  is_active:   model.boolean(),
+  sort_order:  model.number(),
+  metadata:    model.json(),
+  status:      model.enum(["active", "archived"]),
+  created_at:  model.dateTime(),
+  updated_at:  model.dateTime(),
+})
+```
+
+`model.id()` automatically creates a `uuid` primary key with `onCreate` auto-generation. `model.dateTime()` fields named `created_at` / `updated_at` are set automatically on create and update.
+
+### `MeridianService` — Auto-generated CRUD
+
+Pass a map of model names to model definitions and receive a class with full CRUD:
+
+```typescript
+import { MeridianService } from "@meridianjs/framework-utils"
+import type { MeridianContainer } from "@meridianjs/types"
+import { Project } from "./models/project.js"
+import { Label } from "./models/label.js"
+
+export class ProjectModuleService extends MeridianService({ Project, Label }) {
+  constructor(container: MeridianContainer) {
+    super(container)
+  }
+
+  // Auto-generated for Project:
+  //   listProjects(filters?, options?)
+  //   listAndCountProjects(filters?, options?)
+  //   retrieveProject(id)
+  //   createProject(data)
+  //   updateProject(id, data)
+  //   deleteProject(id)
+  //   softDeleteProject(id)
+
+  // Auto-generated for Label:
+  //   listLabels, retrieveLabel, createLabel, updateLabel, deleteLabel ...
+
+  // Add custom methods here
+}
+```
+
+### `Module()` — Module Definition
+
+Register a service + its models and loaders with the DI container:
+
+```typescript
+import { Module } from "@meridianjs/framework-utils"
+
+export default Module("projectModuleService", {
+  service: ProjectModuleService,
+  models: [Project, Label, Milestone],
+  loaders: [defaultLoader],
+  linkable: {
+    project: { tableName: "project", primaryKey: "id" },
+  },
+})
+```
+
+The `key` (first argument) is the container registration token — this is the name used in `container.resolve("projectModuleService")` and in route handlers via `req.scope.resolve("projectModuleService")`.
+
+### `defineLink()` — Cross-module Relationships
+
+Declare a join table between two modules without coupling them via foreign keys:
+
+```typescript
+import { defineLink } from "@meridianjs/framework-utils"
+import ProjectModule from "@meridianjs/project"
+import IssueModule from "@meridianjs/issue"
+
+export default defineLink(
+  { linkable: ProjectModule.linkable!.project },
+  { linkable: IssueModule.linkable!.issue, isList: true, deleteCascades: true },
+  { linkTableName: "project_issue_link", entryPoint: "projectIssueLink" }
+)
+```
+
+### ORM Utilities
+
+Used inside module loaders to initialise per-module MikroORM instances:
+
+```typescript
+import { dmlToEntitySchema, createModuleOrm, createRepository } from "@meridianjs/framework-utils"
+import type { LoaderOptions } from "@meridianjs/types"
+import { Project } from "../models/project.js"
+
+const ProjectSchema = dmlToEntitySchema(Project)
+
+export default async function defaultLoader({ container }: LoaderOptions) {
+  const config = container.resolve("config") as any
+  const orm = await createModuleOrm([ProjectSchema], config.projectConfig.databaseUrl)
+  const em = orm.em.fork()
+  container.register({
+    projectRepository: createRepository(em, "project"),
+    projectOrm: orm,
+  })
+}
+```
+
+Each module manages its own `MikroORM` instance and schema, keeping modules fully isolated from one another.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -156,12 +156,6 @@ type InferModel<M extends ModelDefinition> = M extends ModelDefinition<infer Sch
  */
 declare function MeridianService(models: Record<string, ModelDefinition>): new (container: MeridianContainer) => IModuleService;
 
-/**
- * Converts a DML ModelDefinition to a MikroORM EntitySchema.
- *
- * Automatically adds `created_at`, `updated_at`, and `deleted_at` timestamp
- * columns to every entity.
- */
 declare function dmlToEntitySchema(def: ModelDefinition): EntitySchema;
 /**
  * Wraps a MikroORM EntityManager into the Repository interface expected

package/dist/index.d.ts

@@ -156,12 +156,6 @@ type InferModel<M extends ModelDefinition> = M extends ModelDefinition<infer Sch
  */
 declare function MeridianService(models: Record<string, ModelDefinition>): new (container: MeridianContainer) => IModuleService;
 
-/**
- * Converts a DML ModelDefinition to a MikroORM EntitySchema.
- *
- * Automatically adds `created_at`, `updated_at`, and `deleted_at` timestamp
- * columns to every entity.
- */
 declare function dmlToEntitySchema(def: ModelDefinition): EntitySchema;
 /**
  * Wraps a MikroORM EntityManager into the Repository interface expected

package/dist/index.js

@@ -55,10 +55,10 @@ function Module(key, definition) {
 
 // src/define-link.ts
 function normalizeEndpoint(input) {
-  if ("linkable" in input) {
-    return input;
+  if ("tableName" in input) {
+    return { linkable: input };
   }
-  return { linkable: input };
+  return input;
 }
 function defineLink(left, right, options) {
   const leftEndpoint = normalizeEndpoint(left);
@@ -184,6 +184,15 @@ var model = {
 };
 
 // src/service-factory.ts
+var UPDATE_RESERVED = /* @__PURE__ */ new Set([
+  "id",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
 function MeridianService(models) {
   class BaseService {
     // Use private class field to avoid conflicting with the index signature
@@ -200,21 +209,21 @@ function MeridianService(models) {
         if (!hasCustomMethod(listMethod)) {
           this[listMethod] = async (filters = {}, options = {}) => {
             const repo = this.#container.resolve(repoToken);
-            return repo.find(filters, options);
+            return repo.find({ deleted_at: null, ...filters }, options);
           };
         }
         const listAndCountMethod = `listAndCount${capitalizedPlural}`;
         if (!hasCustomMethod(listAndCountMethod)) {
           this[listAndCountMethod] = async (filters = {}, options = {}) => {
             const repo = this.#container.resolve(repoToken);
-            return repo.findAndCount(filters, options);
+            return repo.findAndCount({ deleted_at: null, ...filters }, options);
           };
         }
         const retrieveMethod = `retrieve${capitalized}`;
         if (!hasCustomMethod(retrieveMethod)) {
           this[retrieveMethod] = async (id) => {
             const repo = this.#container.resolve(repoToken);
-            return repo.findOneOrFail({ id });
+            return repo.findOneOrFail({ id, deleted_at: null });
           };
         }
         const createMethod = `create${capitalized}`;
@@ -230,8 +239,11 @@ function MeridianService(models) {
         if (!hasCustomMethod(updateMethod)) {
           this[updateMethod] = async (id, data) => {
             const repo = this.#container.resolve(repoToken);
-            const entity = await repo.findOneOrFail({ id });
-            Object.assign(entity, data);
+            const entity = await repo.findOneOrFail({ id, deleted_at: null });
+            const safe = Object.fromEntries(
+              Object.entries(data).filter(([k]) => !UPDATE_RESERVED.has(k))
+            );
+            Object.assign(entity, safe);
             await repo.flush();
             return entity;
           };
@@ -248,7 +260,7 @@ function MeridianService(models) {
         if (!hasCustomMethod(softDeleteMethod)) {
           this[softDeleteMethod] = async (id) => {
             const repo = this.#container.resolve(repoToken);
-            const entity = await repo.findOneOrFail({ id });
+            const entity = await repo.findOneOrFail({ id, deleted_at: null });
             entity.deleted_at = /* @__PURE__ */ new Date();
             await repo.flush();
             return entity;
@@ -262,7 +274,15 @@ function MeridianService(models) {
 
 // src/orm-utils.ts
 var import_core = require("@mikro-orm/core");
+var RESERVED_TIMESTAMP_KEYS = ["created_at", "updated_at", "deleted_at"];
 function dmlToEntitySchema(def) {
+  for (const key of RESERVED_TIMESTAMP_KEYS) {
+    if (key in def.schema) {
+      throw new Error(
+        `Model "${def.tableName}" defines reserved column "${key}". Meridian automatically manages created_at, updated_at, and deleted_at.`
+      );
+    }
+  }
   const properties = {};
   for (const [key, prop] of Object.entries(def.schema)) {
     if (prop instanceof IdProperty) {
@@ -344,9 +364,10 @@ function createRepository(em, entityName) {
       return repo.find(filters, options);
     },
     async findAndCount(filters, options = {}) {
+      const { limit, offset, ...countOptions } = options;
       const [data, count] = await Promise.all([
         repo.find(filters, options),
-        repo.count(filters)
+        repo.count(filters, countOptions)
       ]);
       return [data, count];
     },

package/dist/index.mjs

@@ -5,10 +5,10 @@ function Module(key, definition) {
 
 // src/define-link.ts
 function normalizeEndpoint(input) {
-  if ("linkable" in input) {
-    return input;
+  if ("tableName" in input) {
+    return { linkable: input };
   }
-  return { linkable: input };
+  return input;
 }
 function defineLink(left, right, options) {
   const leftEndpoint = normalizeEndpoint(left);
@@ -134,6 +134,15 @@ var model = {
 };
 
 // src/service-factory.ts
+var UPDATE_RESERVED = /* @__PURE__ */ new Set([
+  "id",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
 function MeridianService(models) {
   class BaseService {
     // Use private class field to avoid conflicting with the index signature
@@ -150,21 +159,21 @@ function MeridianService(models) {
         if (!hasCustomMethod(listMethod)) {
           this[listMethod] = async (filters = {}, options = {}) => {
             const repo = this.#container.resolve(repoToken);
-            return repo.find(filters, options);
+            return repo.find({ deleted_at: null, ...filters }, options);
           };
         }
         const listAndCountMethod = `listAndCount${capitalizedPlural}`;
         if (!hasCustomMethod(listAndCountMethod)) {
           this[listAndCountMethod] = async (filters = {}, options = {}) => {
             const repo = this.#container.resolve(repoToken);
-            return repo.findAndCount(filters, options);
+            return repo.findAndCount({ deleted_at: null, ...filters }, options);
           };
         }
         const retrieveMethod = `retrieve${capitalized}`;
         if (!hasCustomMethod(retrieveMethod)) {
           this[retrieveMethod] = async (id) => {
             const repo = this.#container.resolve(repoToken);
-            return repo.findOneOrFail({ id });
+            return repo.findOneOrFail({ id, deleted_at: null });
           };
         }
         const createMethod = `create${capitalized}`;
@@ -180,8 +189,11 @@ function MeridianService(models) {
         if (!hasCustomMethod(updateMethod)) {
           this[updateMethod] = async (id, data) => {
             const repo = this.#container.resolve(repoToken);
-            const entity = await repo.findOneOrFail({ id });
-            Object.assign(entity, data);
+            const entity = await repo.findOneOrFail({ id, deleted_at: null });
+            const safe = Object.fromEntries(
+              Object.entries(data).filter(([k]) => !UPDATE_RESERVED.has(k))
+            );
+            Object.assign(entity, safe);
             await repo.flush();
             return entity;
           };
@@ -198,7 +210,7 @@ function MeridianService(models) {
         if (!hasCustomMethod(softDeleteMethod)) {
           this[softDeleteMethod] = async (id) => {
             const repo = this.#container.resolve(repoToken);
-            const entity = await repo.findOneOrFail({ id });
+            const entity = await repo.findOneOrFail({ id, deleted_at: null });
             entity.deleted_at = /* @__PURE__ */ new Date();
             await repo.flush();
             return entity;
@@ -212,7 +224,15 @@ function MeridianService(models) {
 
 // src/orm-utils.ts
 import { EntitySchema } from "@mikro-orm/core";
+var RESERVED_TIMESTAMP_KEYS = ["created_at", "updated_at", "deleted_at"];
 function dmlToEntitySchema(def) {
+  for (const key of RESERVED_TIMESTAMP_KEYS) {
+    if (key in def.schema) {
+      throw new Error(
+        `Model "${def.tableName}" defines reserved column "${key}". Meridian automatically manages created_at, updated_at, and deleted_at.`
+      );
+    }
+  }
   const properties = {};
   for (const [key, prop] of Object.entries(def.schema)) {
     if (prop instanceof IdProperty) {
@@ -294,9 +314,10 @@ function createRepository(em, entityName) {
       return repo.find(filters, options);
     },
     async findAndCount(filters, options = {}) {
+      const { limit, offset, ...countOptions } = options;
       const [data, count] = await Promise.all([
         repo.find(filters, options),
-        repo.count(filters)
+        repo.count(filters, countOptions)
       ]);
       return [data, count];
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meridianjs/framework-utils",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Utilities for building Meridian modules: DML, service factory, defineModule, defineLink",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",