@meridianjs/framework-utils 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,199 @@
+import { ModuleDefinition, LinkableEntry, LinkEndpoint, LinkDefinition, MeridianContainer, IModuleService } from '@meridianjs/types';
+import { EntitySchema, MikroORM, EntityManager } from '@mikro-orm/core';
+
+/**
+ * Declares a Meridian module.
+ *
+ * @example
+ * export default Module("projectModuleService", {
+ *   service: ProjectModuleService,
+ *   models: [Project, Label],
+ *   loaders: [defaultLoader],
+ *   linkable: { project: { tableName: "project", primaryKey: "id" } },
+ * })
+ */
+declare function Module(key: string, definition: Omit<ModuleDefinition, "key">): ModuleDefinition;
+
+type LinkEndpointInput = LinkableEntry | LinkEndpoint;
+/**
+ * Defines a cross-module relationship as a junction table.
+ * Neither module holds a foreign key — the link table is independent.
+ *
+ * @example
+ * export default defineLink(
+ *   ProjectModule.linkable.project,
+ *   { linkable: IssueModule.linkable.issue, isList: true }
+ * )
+ */
+declare function defineLink(left: LinkEndpointInput, right: LinkEndpointInput, options?: {
+    readOnly?: boolean;
+    database?: {
+        extraColumns?: Record<string, {
+            type: string;
+        }>;
+    };
+}): LinkDefinition;
+
+/**
+ * Data Model Language (DML) — fluent API for defining Meridian data models.
+ *
+ * Each model definition is later converted to a database schema by the module loader.
+ * The actual ORM entity class is generated at runtime from this specification.
+ *
+ * @example
+ * const Project = model.define("project", {
+ *   id: model.id().primaryKey(),
+ *   name: model.text(),
+ *   visibility: model.enum(["private", "public", "workspace"]),
+ *   description: model.text().nullable(),
+ * })
+ */
+declare class IdProperty {
+    readonly _type: "id";
+    _primaryKey: boolean;
+    primaryKey(): this;
+}
+declare class TextProperty {
+    readonly _type: "text";
+    _nullable: boolean;
+    _default?: string;
+    nullable(): this;
+    default(val: string): this;
+}
+declare class BooleanProperty {
+    readonly _type: "boolean";
+    _default?: boolean;
+    default(val: boolean): this;
+}
+declare class NumberProperty {
+    readonly _type: "number";
+    _nullable: boolean;
+    _default?: number;
+    nullable(): this;
+    default(val: number): this;
+}
+declare class DateProperty {
+    readonly _type: "date";
+    _nullable: boolean;
+    nullable(): this;
+}
+declare class JsonProperty {
+    readonly _type: "json";
+    _nullable: boolean;
+    nullable(): this;
+}
+declare class EnumProperty<T extends string> {
+    readonly _values: T[];
+    readonly _type: "enum";
+    constructor(_values: T[]);
+    _nullable: boolean;
+    _default?: T;
+    nullable(): this;
+    default(val: T): this;
+}
+type PropertyType = IdProperty | TextProperty | BooleanProperty | NumberProperty | DateProperty | JsonProperty | EnumProperty<string>;
+type ModelSchema = Record<string, PropertyType>;
+interface IndexDefinition {
+    /** Column names that form the index. */
+    columns: string[];
+    /** Whether this is a unique index. Defaults to false. */
+    unique?: boolean;
+    /** Optional explicit index name. MikroORM will auto-generate one if omitted. */
+    name?: string;
+}
+declare class ModelDefinition<Schema extends ModelSchema = ModelSchema> {
+    readonly tableName: string;
+    readonly schema: Schema;
+    readonly indexes: IndexDefinition[];
+    constructor(tableName: string, schema: Schema, indexes?: IndexDefinition[]);
+}
+declare const model: {
+    /**
+     * Define a new data model. The table name should be snake_case singular.
+     * Optionally pass index definitions as the third argument.
+     */
+    define<Schema extends ModelSchema>(tableName: string, schema: Schema, indexes?: IndexDefinition[]): ModelDefinition<Schema>;
+    /** UUID primary key field */
+    id: () => IdProperty;
+    /** Variable-length text / varchar */
+    text: () => TextProperty;
+    /** Boolean true/false */
+    boolean: () => BooleanProperty;
+    /** Integer or float */
+    number: () => NumberProperty;
+    /** Timestamp with timezone */
+    date: () => DateProperty;
+    /** JSONB column */
+    json: () => JsonProperty;
+    /** Enum column — values are enforced at application level */
+    enum: <T extends string>(values: T[]) => EnumProperty<T>;
+};
+type InferPropertyType<P extends PropertyType> = P extends IdProperty ? string : P extends TextProperty ? (P["_nullable"] extends true ? string | null : string) : P extends BooleanProperty ? boolean : P extends NumberProperty ? (P["_nullable"] extends true ? number | null : number) : P extends DateProperty ? (P["_nullable"] extends true ? Date | null : Date) : P extends JsonProperty ? (P["_nullable"] extends true ? unknown | null : unknown) : P extends EnumProperty<infer T> ? T : never;
+type InferModel<M extends ModelDefinition> = M extends ModelDefinition<infer Schema> ? {
+    [K in keyof Schema]: InferPropertyType<Schema[K]>;
+} & {
+    created_at: Date;
+    updated_at: Date;
+    deleted_at: Date | null;
+} : never;
+
+/**
+ * Base class factory that auto-generates CRUD methods for each model.
+ *
+ * For a model named "Project", the following methods are generated:
+ *   - listProjects(filters?, options?) → Promise<Project[]>
+ *   - listAndCountProjects(filters?, options?) → Promise<[Project[], number]>
+ *   - retrieveProject(id) → Promise<Project>
+ *   - createProject(data) → Promise<Project>
+ *   - updateProject(id, data) → Promise<Project>
+ *   - deleteProject(id) → Promise<void>
+ *   - softDeleteProject(id) → Promise<Project>
+ *
+ * @example
+ * class ProjectModuleService extends MeridianService({ Project, Label }) {
+ *   constructor(container: MeridianContainer) { super(container) }
+ * }
+ */
+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
+ * by MeridianService's auto-generated CRUD methods.
+ *
+ * The `entityName` is the DML model's tableName (e.g. "user", "workspace").
+ * The resulting object is registered in the module container as `${entityName}Repository`.
+ */
+declare function createRepository(em: EntityManager, entityName: string): MeridianRepository;
+interface MeridianRepository {
+    find(filters: object, options?: object): Promise<unknown[]>;
+    findAndCount(filters: object, options?: object): Promise<[unknown[], number]>;
+    findOne(filters: object): Promise<unknown | null>;
+    findOneOrFail(filters: object): Promise<unknown>;
+    create(data: object): unknown;
+    persistAndFlush(entity: unknown): Promise<void>;
+    flush(): Promise<void>;
+    removeAndFlush(entity: unknown): Promise<void>;
+}
+/**
+ * Creates a MikroORM instance for a module's set of entities.
+ *
+ * In development (NODE_ENV !== "production"), schema is automatically
+ * synced to the database (safe mode — only adds, never drops).
+ *
+ * @param entitySchemas - MikroORM EntitySchema objects for this module's models
+ * @param databaseUrl - PostgreSQL connection URL
+ * @param sync - auto-sync schema (default: true in development)
+ */
+declare function createModuleOrm(entitySchemas: EntitySchema[], databaseUrl: string, options?: {
+    sync?: boolean;
+    debug?: boolean;
+}): Promise<MikroORM>;
+
+export { BooleanProperty, DateProperty, EnumProperty, IdProperty, type IndexDefinition, type InferModel, JsonProperty, type MeridianRepository, MeridianService, ModelDefinition, type ModelSchema, Module, NumberProperty, TextProperty, createModuleOrm, createRepository, defineLink, dmlToEntitySchema, model };

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import { ModuleDefinition, LinkableEntry, LinkEndpoint, LinkDefinition, MeridianContainer, IModuleService } from '@meridianjs/types';
+import { EntitySchema, MikroORM, EntityManager } from '@mikro-orm/core';
+
+/**
+ * Declares a Meridian module.
+ *
+ * @example
+ * export default Module("projectModuleService", {
+ *   service: ProjectModuleService,
+ *   models: [Project, Label],
+ *   loaders: [defaultLoader],
+ *   linkable: { project: { tableName: "project", primaryKey: "id" } },
+ * })
+ */
+declare function Module(key: string, definition: Omit<ModuleDefinition, "key">): ModuleDefinition;
+
+type LinkEndpointInput = LinkableEntry | LinkEndpoint;
+/**
+ * Defines a cross-module relationship as a junction table.
+ * Neither module holds a foreign key — the link table is independent.
+ *
+ * @example
+ * export default defineLink(
+ *   ProjectModule.linkable.project,
+ *   { linkable: IssueModule.linkable.issue, isList: true }
+ * )
+ */
+declare function defineLink(left: LinkEndpointInput, right: LinkEndpointInput, options?: {
+    readOnly?: boolean;
+    database?: {
+        extraColumns?: Record<string, {
+            type: string;
+        }>;
+    };
+}): LinkDefinition;
+
+/**
+ * Data Model Language (DML) — fluent API for defining Meridian data models.
+ *
+ * Each model definition is later converted to a database schema by the module loader.
+ * The actual ORM entity class is generated at runtime from this specification.
+ *
+ * @example
+ * const Project = model.define("project", {
+ *   id: model.id().primaryKey(),
+ *   name: model.text(),
+ *   visibility: model.enum(["private", "public", "workspace"]),
+ *   description: model.text().nullable(),
+ * })
+ */
+declare class IdProperty {
+    readonly _type: "id";
+    _primaryKey: boolean;
+    primaryKey(): this;
+}
+declare class TextProperty {
+    readonly _type: "text";
+    _nullable: boolean;
+    _default?: string;
+    nullable(): this;
+    default(val: string): this;
+}
+declare class BooleanProperty {
+    readonly _type: "boolean";
+    _default?: boolean;
+    default(val: boolean): this;
+}
+declare class NumberProperty {
+    readonly _type: "number";
+    _nullable: boolean;
+    _default?: number;
+    nullable(): this;
+    default(val: number): this;
+}
+declare class DateProperty {
+    readonly _type: "date";
+    _nullable: boolean;
+    nullable(): this;
+}
+declare class JsonProperty {
+    readonly _type: "json";
+    _nullable: boolean;
+    nullable(): this;
+}
+declare class EnumProperty<T extends string> {
+    readonly _values: T[];
+    readonly _type: "enum";
+    constructor(_values: T[]);
+    _nullable: boolean;
+    _default?: T;
+    nullable(): this;
+    default(val: T): this;
+}
+type PropertyType = IdProperty | TextProperty | BooleanProperty | NumberProperty | DateProperty | JsonProperty | EnumProperty<string>;
+type ModelSchema = Record<string, PropertyType>;
+interface IndexDefinition {
+    /** Column names that form the index. */
+    columns: string[];
+    /** Whether this is a unique index. Defaults to false. */
+    unique?: boolean;
+    /** Optional explicit index name. MikroORM will auto-generate one if omitted. */
+    name?: string;
+}
+declare class ModelDefinition<Schema extends ModelSchema = ModelSchema> {
+    readonly tableName: string;
+    readonly schema: Schema;
+    readonly indexes: IndexDefinition[];
+    constructor(tableName: string, schema: Schema, indexes?: IndexDefinition[]);
+}
+declare const model: {
+    /**
+     * Define a new data model. The table name should be snake_case singular.
+     * Optionally pass index definitions as the third argument.
+     */
+    define<Schema extends ModelSchema>(tableName: string, schema: Schema, indexes?: IndexDefinition[]): ModelDefinition<Schema>;
+    /** UUID primary key field */
+    id: () => IdProperty;
+    /** Variable-length text / varchar */
+    text: () => TextProperty;
+    /** Boolean true/false */
+    boolean: () => BooleanProperty;
+    /** Integer or float */
+    number: () => NumberProperty;
+    /** Timestamp with timezone */
+    date: () => DateProperty;
+    /** JSONB column */
+    json: () => JsonProperty;
+    /** Enum column — values are enforced at application level */
+    enum: <T extends string>(values: T[]) => EnumProperty<T>;
+};
+type InferPropertyType<P extends PropertyType> = P extends IdProperty ? string : P extends TextProperty ? (P["_nullable"] extends true ? string | null : string) : P extends BooleanProperty ? boolean : P extends NumberProperty ? (P["_nullable"] extends true ? number | null : number) : P extends DateProperty ? (P["_nullable"] extends true ? Date | null : Date) : P extends JsonProperty ? (P["_nullable"] extends true ? unknown | null : unknown) : P extends EnumProperty<infer T> ? T : never;
+type InferModel<M extends ModelDefinition> = M extends ModelDefinition<infer Schema> ? {
+    [K in keyof Schema]: InferPropertyType<Schema[K]>;
+} & {
+    created_at: Date;
+    updated_at: Date;
+    deleted_at: Date | null;
+} : never;
+
+/**
+ * Base class factory that auto-generates CRUD methods for each model.
+ *
+ * For a model named "Project", the following methods are generated:
+ *   - listProjects(filters?, options?) → Promise<Project[]>
+ *   - listAndCountProjects(filters?, options?) → Promise<[Project[], number]>
+ *   - retrieveProject(id) → Promise<Project>
+ *   - createProject(data) → Promise<Project>
+ *   - updateProject(id, data) → Promise<Project>
+ *   - deleteProject(id) → Promise<void>
+ *   - softDeleteProject(id) → Promise<Project>
+ *
+ * @example
+ * class ProjectModuleService extends MeridianService({ Project, Label }) {
+ *   constructor(container: MeridianContainer) { super(container) }
+ * }
+ */
+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
+ * by MeridianService's auto-generated CRUD methods.
+ *
+ * The `entityName` is the DML model's tableName (e.g. "user", "workspace").
+ * The resulting object is registered in the module container as `${entityName}Repository`.
+ */
+declare function createRepository(em: EntityManager, entityName: string): MeridianRepository;
+interface MeridianRepository {
+    find(filters: object, options?: object): Promise<unknown[]>;
+    findAndCount(filters: object, options?: object): Promise<[unknown[], number]>;
+    findOne(filters: object): Promise<unknown | null>;
+    findOneOrFail(filters: object): Promise<unknown>;
+    create(data: object): unknown;
+    persistAndFlush(entity: unknown): Promise<void>;
+    flush(): Promise<void>;
+    removeAndFlush(entity: unknown): Promise<void>;
+}
+/**
+ * Creates a MikroORM instance for a module's set of entities.
+ *
+ * In development (NODE_ENV !== "production"), schema is automatically
+ * synced to the database (safe mode — only adds, never drops).
+ *
+ * @param entitySchemas - MikroORM EntitySchema objects for this module's models
+ * @param databaseUrl - PostgreSQL connection URL
+ * @param sync - auto-sync schema (default: true in development)
+ */
+declare function createModuleOrm(entitySchemas: EntitySchema[], databaseUrl: string, options?: {
+    sync?: boolean;
+    debug?: boolean;
+}): Promise<MikroORM>;
+
+export { BooleanProperty, DateProperty, EnumProperty, IdProperty, type IndexDefinition, type InferModel, JsonProperty, type MeridianRepository, MeridianService, ModelDefinition, type ModelSchema, Module, NumberProperty, TextProperty, createModuleOrm, createRepository, defineLink, dmlToEntitySchema, model };

package/dist/index.js

@@ -0,0 +1,384 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BooleanProperty: () => BooleanProperty,
+  DateProperty: () => DateProperty,
+  EnumProperty: () => EnumProperty,
+  IdProperty: () => IdProperty,
+  JsonProperty: () => JsonProperty,
+  MeridianService: () => MeridianService,
+  ModelDefinition: () => ModelDefinition,
+  Module: () => Module,
+  NumberProperty: () => NumberProperty,
+  TextProperty: () => TextProperty,
+  createModuleOrm: () => createModuleOrm,
+  createRepository: () => createRepository,
+  defineLink: () => defineLink,
+  dmlToEntitySchema: () => dmlToEntitySchema,
+  model: () => model
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/define-module.ts
+function Module(key, definition) {
+  return { key, ...definition };
+}
+
+// src/define-link.ts
+function normalizeEndpoint(input) {
+  if ("linkable" in input) {
+    return input;
+  }
+  return { linkable: input };
+}
+function defineLink(left, right, options) {
+  const leftEndpoint = normalizeEndpoint(left);
+  const rightEndpoint = normalizeEndpoint(right);
+  const linkTableName = [
+    leftEndpoint.linkable.tableName,
+    rightEndpoint.linkable.tableName
+  ].join("_");
+  return {
+    left: leftEndpoint,
+    right: rightEndpoint,
+    readOnly: options?.readOnly,
+    extraColumns: options?.database?.extraColumns,
+    linkTableName,
+    entryPoint: linkTableName
+  };
+}
+
+// src/dml.ts
+var IdProperty = class {
+  _type = "id";
+  _primaryKey = false;
+  primaryKey() {
+    this._primaryKey = true;
+    return this;
+  }
+};
+var TextProperty = class {
+  _type = "text";
+  _nullable = false;
+  _default;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var BooleanProperty = class {
+  _type = "boolean";
+  _default;
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var NumberProperty = class {
+  _type = "number";
+  _nullable = false;
+  _default;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var DateProperty = class {
+  _type = "date";
+  _nullable = false;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+};
+var JsonProperty = class {
+  _type = "json";
+  _nullable = false;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+};
+var EnumProperty = class {
+  constructor(_values) {
+    this._values = _values;
+  }
+  _type = "enum";
+  _nullable = false;
+  _default;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var ModelDefinition = class {
+  constructor(tableName, schema, indexes = []) {
+    this.tableName = tableName;
+    this.schema = schema;
+    this.indexes = indexes;
+  }
+};
+var model = {
+  /**
+   * Define a new data model. The table name should be snake_case singular.
+   * Optionally pass index definitions as the third argument.
+   */
+  define(tableName, schema, indexes) {
+    return new ModelDefinition(tableName, schema, indexes ?? []);
+  },
+  /** UUID primary key field */
+  id: () => new IdProperty(),
+  /** Variable-length text / varchar */
+  text: () => new TextProperty(),
+  /** Boolean true/false */
+  boolean: () => new BooleanProperty(),
+  /** Integer or float */
+  number: () => new NumberProperty(),
+  /** Timestamp with timezone */
+  date: () => new DateProperty(),
+  /** JSONB column */
+  json: () => new JsonProperty(),
+  /** Enum column — values are enforced at application level */
+  enum: (values) => new EnumProperty(values)
+};
+
+// src/service-factory.ts
+function MeridianService(models) {
+  class BaseService {
+    // Use private class field to avoid conflicting with the index signature
+    #container;
+    constructor(container) {
+      this.#container = container;
+      for (const [modelName, _modelDef] of Object.entries(models)) {
+        const pluralName = `${modelName}s`;
+        const repoToken = `${modelName.charAt(0).toLowerCase()}${modelName.slice(1)}Repository`;
+        const capitalized = `${modelName.charAt(0).toUpperCase()}${modelName.slice(1)}`;
+        const capitalizedPlural = `${pluralName.charAt(0).toUpperCase()}${pluralName.slice(1)}`;
+        this[`list${capitalizedPlural}`] = async (filters = {}, options = {}) => {
+          const repo = this.#container.resolve(repoToken);
+          return repo.find(filters, options);
+        };
+        this[`listAndCount${capitalizedPlural}`] = async (filters = {}, options = {}) => {
+          const repo = this.#container.resolve(repoToken);
+          return repo.findAndCount(filters, options);
+        };
+        this[`retrieve${capitalized}`] = async (id) => {
+          const repo = this.#container.resolve(repoToken);
+          return repo.findOneOrFail({ id });
+        };
+        this[`create${capitalized}`] = async (data) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = repo.create(data);
+          await repo.persistAndFlush(entity);
+          return entity;
+        };
+        this[`update${capitalized}`] = async (id, data) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = await repo.findOneOrFail({ id });
+          Object.assign(entity, data);
+          await repo.flush();
+          return entity;
+        };
+        this[`delete${capitalized}`] = async (id) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = await repo.findOneOrFail({ id });
+          await repo.removeAndFlush(entity);
+        };
+        this[`softDelete${capitalized}`] = async (id) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = await repo.findOneOrFail({ id });
+          entity.deleted_at = /* @__PURE__ */ new Date();
+          await repo.flush();
+          return entity;
+        };
+      }
+    }
+  }
+  return BaseService;
+}
+
+// src/orm-utils.ts
+var import_core = require("@mikro-orm/core");
+function dmlToEntitySchema(def) {
+  const properties = {};
+  for (const [key, prop] of Object.entries(def.schema)) {
+    if (prop instanceof IdProperty) {
+      properties[key] = {
+        type: "uuid",
+        primary: prop._primaryKey,
+        defaultRaw: "gen_random_uuid()",
+        nullable: false
+      };
+    } else if (prop instanceof TextProperty) {
+      properties[key] = {
+        type: "text",
+        nullable: prop._nullable,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    } else if (prop instanceof BooleanProperty) {
+      properties[key] = {
+        type: "boolean",
+        nullable: false,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    } else if (prop instanceof NumberProperty) {
+      properties[key] = {
+        type: "integer",
+        nullable: prop._nullable,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    } else if (prop instanceof DateProperty) {
+      properties[key] = {
+        type: "Date",
+        nullable: prop._nullable
+      };
+    } else if (prop instanceof JsonProperty) {
+      properties[key] = {
+        type: "json",
+        nullable: prop._nullable
+      };
+    } else if (prop instanceof EnumProperty) {
+      properties[key] = {
+        type: "string",
+        nullable: prop._nullable,
+        enum: true,
+        items: prop._values,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    }
+  }
+  properties.created_at = {
+    type: "Date",
+    nullable: false,
+    onCreate: () => /* @__PURE__ */ new Date()
+  };
+  properties.updated_at = {
+    type: "Date",
+    nullable: false,
+    onCreate: () => /* @__PURE__ */ new Date(),
+    onUpdate: () => /* @__PURE__ */ new Date()
+  };
+  properties.deleted_at = {
+    type: "Date",
+    nullable: true
+  };
+  const indexes = (def.indexes ?? []).map((idx) => ({
+    ...idx.name ? { name: idx.name } : {},
+    properties: idx.columns,
+    unique: idx.unique ?? false
+  }));
+  return new import_core.EntitySchema({
+    name: def.tableName,
+    tableName: def.tableName,
+    properties,
+    ...indexes.length > 0 ? { indexes } : {}
+  });
+}
+function createRepository(em, entityName) {
+  const repo = em.getRepository(entityName);
+  return {
+    async find(filters, options = {}) {
+      return repo.find(filters, options);
+    },
+    async findAndCount(filters, options = {}) {
+      const [data, count] = await Promise.all([
+        repo.find(filters, options),
+        repo.count(filters)
+      ]);
+      return [data, count];
+    },
+    async findOne(filters) {
+      return repo.findOne(filters);
+    },
+    async findOneOrFail(filters) {
+      return repo.findOneOrFail(filters);
+    },
+    create(data) {
+      return repo.create(data);
+    },
+    async persistAndFlush(entity) {
+      await em.persistAndFlush(entity);
+    },
+    async flush() {
+      await em.flush();
+    },
+    async removeAndFlush(entity) {
+      await em.removeAndFlush(entity);
+    }
+  };
+}
+async function createModuleOrm(entitySchemas, databaseUrl, options = {}) {
+  const { MikroORM } = await import("@mikro-orm/core");
+  const { PostgreSqlDriver } = await import("@mikro-orm/postgresql");
+  const orm = await MikroORM.init({
+    entities: entitySchemas,
+    clientUrl: databaseUrl,
+    driver: PostgreSqlDriver,
+    debug: options.debug ?? false
+  });
+  const shouldSync = options.sync ?? process.env.NODE_ENV !== "production";
+  if (shouldSync) {
+    const generator = orm.getSchemaGenerator();
+    await generator.updateSchema({ safe: true });
+  }
+  return orm;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BooleanProperty,
+  DateProperty,
+  EnumProperty,
+  IdProperty,
+  JsonProperty,
+  MeridianService,
+  ModelDefinition,
+  Module,
+  NumberProperty,
+  TextProperty,
+  createModuleOrm,
+  createRepository,
+  defineLink,
+  dmlToEntitySchema,
+  model
+});

package/dist/index.mjs

@@ -0,0 +1,333 @@
+// src/define-module.ts
+function Module(key, definition) {
+  return { key, ...definition };
+}
+
+// src/define-link.ts
+function normalizeEndpoint(input) {
+  if ("linkable" in input) {
+    return input;
+  }
+  return { linkable: input };
+}
+function defineLink(left, right, options) {
+  const leftEndpoint = normalizeEndpoint(left);
+  const rightEndpoint = normalizeEndpoint(right);
+  const linkTableName = [
+    leftEndpoint.linkable.tableName,
+    rightEndpoint.linkable.tableName
+  ].join("_");
+  return {
+    left: leftEndpoint,
+    right: rightEndpoint,
+    readOnly: options?.readOnly,
+    extraColumns: options?.database?.extraColumns,
+    linkTableName,
+    entryPoint: linkTableName
+  };
+}
+
+// src/dml.ts
+var IdProperty = class {
+  _type = "id";
+  _primaryKey = false;
+  primaryKey() {
+    this._primaryKey = true;
+    return this;
+  }
+};
+var TextProperty = class {
+  _type = "text";
+  _nullable = false;
+  _default;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var BooleanProperty = class {
+  _type = "boolean";
+  _default;
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var NumberProperty = class {
+  _type = "number";
+  _nullable = false;
+  _default;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var DateProperty = class {
+  _type = "date";
+  _nullable = false;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+};
+var JsonProperty = class {
+  _type = "json";
+  _nullable = false;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+};
+var EnumProperty = class {
+  constructor(_values) {
+    this._values = _values;
+  }
+  _type = "enum";
+  _nullable = false;
+  _default;
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+  default(val) {
+    this._default = val;
+    return this;
+  }
+};
+var ModelDefinition = class {
+  constructor(tableName, schema, indexes = []) {
+    this.tableName = tableName;
+    this.schema = schema;
+    this.indexes = indexes;
+  }
+};
+var model = {
+  /**
+   * Define a new data model. The table name should be snake_case singular.
+   * Optionally pass index definitions as the third argument.
+   */
+  define(tableName, schema, indexes) {
+    return new ModelDefinition(tableName, schema, indexes ?? []);
+  },
+  /** UUID primary key field */
+  id: () => new IdProperty(),
+  /** Variable-length text / varchar */
+  text: () => new TextProperty(),
+  /** Boolean true/false */
+  boolean: () => new BooleanProperty(),
+  /** Integer or float */
+  number: () => new NumberProperty(),
+  /** Timestamp with timezone */
+  date: () => new DateProperty(),
+  /** JSONB column */
+  json: () => new JsonProperty(),
+  /** Enum column — values are enforced at application level */
+  enum: (values) => new EnumProperty(values)
+};
+
+// src/service-factory.ts
+function MeridianService(models) {
+  class BaseService {
+    // Use private class field to avoid conflicting with the index signature
+    #container;
+    constructor(container) {
+      this.#container = container;
+      for (const [modelName, _modelDef] of Object.entries(models)) {
+        const pluralName = `${modelName}s`;
+        const repoToken = `${modelName.charAt(0).toLowerCase()}${modelName.slice(1)}Repository`;
+        const capitalized = `${modelName.charAt(0).toUpperCase()}${modelName.slice(1)}`;
+        const capitalizedPlural = `${pluralName.charAt(0).toUpperCase()}${pluralName.slice(1)}`;
+        this[`list${capitalizedPlural}`] = async (filters = {}, options = {}) => {
+          const repo = this.#container.resolve(repoToken);
+          return repo.find(filters, options);
+        };
+        this[`listAndCount${capitalizedPlural}`] = async (filters = {}, options = {}) => {
+          const repo = this.#container.resolve(repoToken);
+          return repo.findAndCount(filters, options);
+        };
+        this[`retrieve${capitalized}`] = async (id) => {
+          const repo = this.#container.resolve(repoToken);
+          return repo.findOneOrFail({ id });
+        };
+        this[`create${capitalized}`] = async (data) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = repo.create(data);
+          await repo.persistAndFlush(entity);
+          return entity;
+        };
+        this[`update${capitalized}`] = async (id, data) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = await repo.findOneOrFail({ id });
+          Object.assign(entity, data);
+          await repo.flush();
+          return entity;
+        };
+        this[`delete${capitalized}`] = async (id) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = await repo.findOneOrFail({ id });
+          await repo.removeAndFlush(entity);
+        };
+        this[`softDelete${capitalized}`] = async (id) => {
+          const repo = this.#container.resolve(repoToken);
+          const entity = await repo.findOneOrFail({ id });
+          entity.deleted_at = /* @__PURE__ */ new Date();
+          await repo.flush();
+          return entity;
+        };
+      }
+    }
+  }
+  return BaseService;
+}
+
+// src/orm-utils.ts
+import { EntitySchema } from "@mikro-orm/core";
+function dmlToEntitySchema(def) {
+  const properties = {};
+  for (const [key, prop] of Object.entries(def.schema)) {
+    if (prop instanceof IdProperty) {
+      properties[key] = {
+        type: "uuid",
+        primary: prop._primaryKey,
+        defaultRaw: "gen_random_uuid()",
+        nullable: false
+      };
+    } else if (prop instanceof TextProperty) {
+      properties[key] = {
+        type: "text",
+        nullable: prop._nullable,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    } else if (prop instanceof BooleanProperty) {
+      properties[key] = {
+        type: "boolean",
+        nullable: false,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    } else if (prop instanceof NumberProperty) {
+      properties[key] = {
+        type: "integer",
+        nullable: prop._nullable,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    } else if (prop instanceof DateProperty) {
+      properties[key] = {
+        type: "Date",
+        nullable: prop._nullable
+      };
+    } else if (prop instanceof JsonProperty) {
+      properties[key] = {
+        type: "json",
+        nullable: prop._nullable
+      };
+    } else if (prop instanceof EnumProperty) {
+      properties[key] = {
+        type: "string",
+        nullable: prop._nullable,
+        enum: true,
+        items: prop._values,
+        ...prop._default !== void 0 ? { default: prop._default } : {}
+      };
+    }
+  }
+  properties.created_at = {
+    type: "Date",
+    nullable: false,
+    onCreate: () => /* @__PURE__ */ new Date()
+  };
+  properties.updated_at = {
+    type: "Date",
+    nullable: false,
+    onCreate: () => /* @__PURE__ */ new Date(),
+    onUpdate: () => /* @__PURE__ */ new Date()
+  };
+  properties.deleted_at = {
+    type: "Date",
+    nullable: true
+  };
+  const indexes = (def.indexes ?? []).map((idx) => ({
+    ...idx.name ? { name: idx.name } : {},
+    properties: idx.columns,
+    unique: idx.unique ?? false
+  }));
+  return new EntitySchema({
+    name: def.tableName,
+    tableName: def.tableName,
+    properties,
+    ...indexes.length > 0 ? { indexes } : {}
+  });
+}
+function createRepository(em, entityName) {
+  const repo = em.getRepository(entityName);
+  return {
+    async find(filters, options = {}) {
+      return repo.find(filters, options);
+    },
+    async findAndCount(filters, options = {}) {
+      const [data, count] = await Promise.all([
+        repo.find(filters, options),
+        repo.count(filters)
+      ]);
+      return [data, count];
+    },
+    async findOne(filters) {
+      return repo.findOne(filters);
+    },
+    async findOneOrFail(filters) {
+      return repo.findOneOrFail(filters);
+    },
+    create(data) {
+      return repo.create(data);
+    },
+    async persistAndFlush(entity) {
+      await em.persistAndFlush(entity);
+    },
+    async flush() {
+      await em.flush();
+    },
+    async removeAndFlush(entity) {
+      await em.removeAndFlush(entity);
+    }
+  };
+}
+async function createModuleOrm(entitySchemas, databaseUrl, options = {}) {
+  const { MikroORM } = await import("@mikro-orm/core");
+  const { PostgreSqlDriver } = await import("@mikro-orm/postgresql");
+  const orm = await MikroORM.init({
+    entities: entitySchemas,
+    clientUrl: databaseUrl,
+    driver: PostgreSqlDriver,
+    debug: options.debug ?? false
+  });
+  const shouldSync = options.sync ?? process.env.NODE_ENV !== "production";
+  if (shouldSync) {
+    const generator = orm.getSchemaGenerator();
+    await generator.updateSchema({ safe: true });
+  }
+  return orm;
+}
+export {
+  BooleanProperty,
+  DateProperty,
+  EnumProperty,
+  IdProperty,
+  JsonProperty,
+  MeridianService,
+  ModelDefinition,
+  Module,
+  NumberProperty,
+  TextProperty,
+  createModuleOrm,
+  createRepository,
+  defineLink,
+  dmlToEntitySchema,
+  model
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@meridianjs/framework-utils",
+  "version": "0.1.0",
+  "description": "Utilities for building Meridian modules: DML, service factory, defineModule, defineLink",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@meridianjs/types": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6.0.0",
+    "@mikro-orm/postgresql": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@mikro-orm/core": {
+      "optional": true
+    },
+    "@mikro-orm/postgresql": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "*"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}