@smounters/data 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 2.3.0 - 2026-07-30
+
+### Added
+- Первые фрагменты: `BaseEntity` (первичный ключ UUIDv7), `AuditableEntity` (+ колонки аудита),
+  `UserSettingBase` (мешок настроек пользователя: секция/ключ/JSON-значение).
+
+Публикуется потому, что появился реальный потребитель: `smounters-apps` наследует базу во всех 111
+сущностях, а `UserSetting` объявляет только таблицу, связь с юзером и уникальность. Схема при переходе
+не изменилась — проверено дампом из метаданных и сравнением расхождения с живой базой до/после.
+
+Фрагмент — абстрактный класс БЕЗ `@Entity`: колонки в пакете, таблица и связи в проекте. Требует
+PostgreSQL 18+ (нативная `uuidv7()`). Проекту с ЧИСЛОВЫМ первичным ключом фрагменты не подходят —
+это осознанная граница, а не недоработка.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio (@smounters)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @smounters/data
+
+Готовые куски модели данных для MikroORM: первичный ключ UUIDv7, колонки аудита, мешок настроек
+пользователя.
+
+```bash
+npm i @smounters/data @mikro-orm/core @mikro-orm/decorators
+```
+
+## Что такое фрагмент
+
+Фрагмент — это **абстрактный класс без `@Entity()`**. Колонки принадлежат пакету, а таблица, индексы
+и связи — проекту. Разделение не случайное: колонки у всех проектов одинаковые, внешние ключи —
+никогда. Поэтому пакет не может объявить связь с вашим пользователем, а вы не обязаны переписывать
+одни и те же четыре колонки аудита в каждом новом сервисе.
+
+| фрагмент | колонки |
+|---|---|
+| `BaseEntity` | `id` — `uuid`, `default uuidv7()` |
+| `AuditableEntity` | то же + `created_at`, `updated_at` (`timestamptz`, серверные значения по умолчанию, `updated_at` обновляется на записи), `created_by`, `updated_by` (`uuid`, допускают NULL) |
+| `UserSettingBase` | то же + `section` (`varchar(50)`, по умолчанию `default`), `key` (`varchar(100)`), `value` (`jsonb`, допускает NULL) |
+
+## Как подключить
+
+```ts
+import { AuditableEntity, UserSettingBase } from "@smounters/data";
+
+@Entity({ tableName: "orders" })
+export class Order extends AuditableEntity {
+  /* свои колонки */
+}
+
+// Связь и уникальность объявляет проект — только он знает, где живут его пользователи.
+@Entity({ tableName: "user_settings" })
+@Unique({ properties: ["user", "section", "key"] })
+export class UserSetting extends UserSettingBase {
+  @ManyToOne(() => User, { deleteRule: "cascade" })
+  @Index()
+  user!: Rel<User>;
+}
+```
+
+`UserSettingBase` — это хранилище, в которое пишет `@smounters/ui` через `UiProvider.useSetting`
+(видимость и порядок колонок таблицы, ширина сайдбара). Значение бэкенд не разбирает: его схему знает
+фронт.
+
+## Требования
+
+- **PostgreSQL 18+**: `id` берёт значение из `uuidv7()`, а эта функция появилась в 18-й версии. На
+  более старом сервере либо завести функцию с таким именем, либо переопределить свойство у себя.
+- `@mikro-orm/core` и `@mikro-orm/decorators` — **peer-зависимости**: ядро ORM в приложении должно
+  быть ровно одно, иначе метаданные окажутся в разных реестрах и сущности «не найдутся».
+- Колонки объявлены с ЯВНЫМ типом у каждого декоратора. Ничего не выводится из
+  `emitDecoratorMetadata`, поэтому собранный пакет ведёт себя так же, как тот же код внутри
+  приложения: отражённые типы через границу пакета не переживают сборку надёжно.
+
+## Порядок колонок
+
+Унаследованные колонки идут в `CREATE TABLE` перед объявленными в проекте, поэтому у уже
+существующей таблицы порядок в свежем дампе будет другим. На сравнение схемы это не влияет: MikroORM
+сверяет набор колонок, а не их порядок, — проверено на 111 сущностях (расхождение с живой базой до и
+после перехода на фрагменты совпало полностью). Переупорядочить колонки в PostgreSQL всё равно нельзя.

package/dist/base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Primary key only. Use when a table needs no audit columns (a join table, an append-only log with
+ * its own timestamp semantics).
+ *
+ * UUIDv7 (time-ordered, RFC 9562): k-sortable, so B-tree inserts keep the locality of a serial key
+ * while the id stays non-enumerable. Generated DB-side into a native `uuid` column — this requires
+ * **PostgreSQL 18+**, which ships `uuidv7()`. On older servers install a shim function of that name
+ * or override the property in the project.
+ */
+export declare abstract class BaseEntity {
+    id: string;
+}
+/**
+ * Primary key + audit columns. The default base for aggregates.
+ *
+ * `createdBy`/`updatedBy` hold the acting user id; null means the system (a worker, a migration, a
+ * seed). They are plain uuid columns rather than relations on purpose: a fragment cannot know which
+ * table your users live in, and an audit column should not create a foreign key that blocks
+ * deleting a user.
+ */
+export declare abstract class AuditableEntity extends BaseEntity {
+    createdAt: Date;
+    updatedAt: Date;
+    createdBy?: string;
+    updatedBy?: string;
+}

package/dist/base.js

@@ -0,0 +1,64 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { PrimaryKey, Property } from "@mikro-orm/decorators/legacy";
+// Entity fragments, not entities: these classes carry NO `@Entity()`. MikroORM inherits decorated
+// properties from an abstract base, so a project extends them and declares its own table name,
+// indexes and relations. That is what makes a fragment reusable across projects whose foreign keys
+// point at different tables.
+//
+// Every decorator here states its column type EXPLICITLY. Nothing is inferred from
+// `emitDecoratorMetadata`, so the built package behaves exactly like the same code compiled inside
+// the consuming project — reflected type metadata does not survive a package boundary reliably.
+/**
+ * Primary key only. Use when a table needs no audit columns (a join table, an append-only log with
+ * its own timestamp semantics).
+ *
+ * UUIDv7 (time-ordered, RFC 9562): k-sortable, so B-tree inserts keep the locality of a serial key
+ * while the id stays non-enumerable. Generated DB-side into a native `uuid` column — this requires
+ * **PostgreSQL 18+**, which ships `uuidv7()`. On older servers install a shim function of that name
+ * or override the property in the project.
+ */
+export class BaseEntity {
+}
+__decorate([
+    PrimaryKey({ type: "uuid", defaultRaw: "uuidv7()" }),
+    __metadata("design:type", String)
+], BaseEntity.prototype, "id", void 0);
+/**
+ * Primary key + audit columns. The default base for aggregates.
+ *
+ * `createdBy`/`updatedBy` hold the acting user id; null means the system (a worker, a migration, a
+ * seed). They are plain uuid columns rather than relations on purpose: a fragment cannot know which
+ * table your users live in, and an audit column should not create a foreign key that blocks
+ * deleting a user.
+ */
+export class AuditableEntity extends BaseEntity {
+    constructor() {
+        super(...arguments);
+        this.createdAt = new Date();
+        this.updatedAt = new Date();
+    }
+}
+__decorate([
+    Property({ type: "timestamptz", length: 0, defaultRaw: "CURRENT_TIMESTAMP" }),
+    __metadata("design:type", Object)
+], AuditableEntity.prototype, "createdAt", void 0);
+__decorate([
+    Property({ type: "timestamptz", length: 0, defaultRaw: "CURRENT_TIMESTAMP", onUpdate: () => new Date() }),
+    __metadata("design:type", Object)
+], AuditableEntity.prototype, "updatedAt", void 0);
+__decorate([
+    Property({ type: "uuid", nullable: true }),
+    __metadata("design:type", String)
+], AuditableEntity.prototype, "createdBy", void 0);
+__decorate([
+    Property({ type: "uuid", nullable: true }),
+    __metadata("design:type", String)
+], AuditableEntity.prototype, "updatedBy", void 0);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AuditableEntity, BaseEntity } from "./base.js";
+export { UserSettingBase } from "./user-setting.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// @smounters/data — MikroORM entity fragments shared by our projects.
+//
+// A fragment is an abstract class WITHOUT `@Entity()`: it owns columns, the project owns the table,
+// the indexes and the relations. That split is deliberate — the columns are the same everywhere, the
+// foreign keys never are.
+export { AuditableEntity, BaseEntity } from "./base.js";
+export { UserSettingBase } from "./user-setting.js";

package/dist/user-setting.d.ts

@@ -0,0 +1,28 @@
+import type { Opt } from "@mikro-orm/core";
+import { AuditableEntity } from "./base.js";
+/**
+ * Per-user preference bag: one row per (user, section, key), the value is arbitrary JSON. The backend
+ * never interprets the value — its shape belongs to the front end (column order and visibility,
+ * sidebar width, filters). This is the store `@smounters/ui` writes through `UiProvider.useSetting`.
+ *
+ * The relation to the user and the unique constraint are declared by the project, because only the
+ * project knows which table its users live in:
+ *
+ * ```ts
+ * @Entity({ tableName: "user_settings" })
+ * @Unique({ properties: ["user", "section", "key"] })
+ * export class UserSetting extends UserSettingBase {
+ *   @ManyToOne(() => User, { deleteRule: "cascade" })
+ *   @Index()
+ *   user!: Rel<User>;
+ * }
+ * ```
+ *
+ * `section` carries a default rather than being nullable so that the unique triple always holds — a
+ * NULL section would let the same key be inserted twice.
+ */
+export declare abstract class UserSettingBase extends AuditableEntity {
+    section: string & Opt;
+    key: string;
+    value?: unknown;
+}

package/dist/user-setting.js

@@ -0,0 +1,50 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Property } from "@mikro-orm/decorators/legacy";
+import { AuditableEntity } from "./base.js";
+/**
+ * Per-user preference bag: one row per (user, section, key), the value is arbitrary JSON. The backend
+ * never interprets the value — its shape belongs to the front end (column order and visibility,
+ * sidebar width, filters). This is the store `@smounters/ui` writes through `UiProvider.useSetting`.
+ *
+ * The relation to the user and the unique constraint are declared by the project, because only the
+ * project knows which table its users live in:
+ *
+ * ```ts
+ * @Entity({ tableName: "user_settings" })
+ * @Unique({ properties: ["user", "section", "key"] })
+ * export class UserSetting extends UserSettingBase {
+ *   @ManyToOne(() => User, { deleteRule: "cascade" })
+ *   @Index()
+ *   user!: Rel<User>;
+ * }
+ * ```
+ *
+ * `section` carries a default rather than being nullable so that the unique triple always holds — a
+ * NULL section would let the same key be inserted twice.
+ */
+export class UserSettingBase extends AuditableEntity {
+    constructor() {
+        super(...arguments);
+        this.section = "default";
+    }
+}
+__decorate([
+    Property({ type: "varchar", length: 50, default: "default" }),
+    __metadata("design:type", Object)
+], UserSettingBase.prototype, "section", void 0);
+__decorate([
+    Property({ type: "varchar", length: 100 }),
+    __metadata("design:type", String)
+], UserSettingBase.prototype, "key", void 0);
+__decorate([
+    Property({ type: "jsonb", nullable: true }),
+    __metadata("design:type", Object)
+], UserSettingBase.prototype, "value", void 0);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@smounters/data",
+  "version": "2.3.0",
+  "description": "Reusable MikroORM entity fragments: UUIDv7 primary key, audit columns, per-user settings bag",
+  "keywords": [
+    "mikro-orm",
+    "entity",
+    "postgres",
+    "uuidv7",
+    "typescript"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smounters/smounters-packages.git",
+    "directory": "packages/data"
+  },
+  "homepage": "https://smounters.github.io/smounters-packages/",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^7",
+    "@mikro-orm/decorators": "^7"
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^7",
+    "@mikro-orm/decorators": "^7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}