mikro-orm-temporal 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025, Ben Scholzen 'DASPRiD'
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,48 @@
+# Temporal for Mikro ORM
+
+[![Release](https://github.com/DASPRiD/mikro-orm-temporal/actions/workflows/release.yml/badge.svg)](https://github.com/DASPRiD/mikro-orm-temporal/actions/workflows/release.yml)
+[![codecov](https://codecov.io/gh/DASPRiD/mikro-orm-temporal/graph/badge.svg?token=s9yDuZeh7F)](https://codecov.io/gh/DASPRiD/mikro-orm-temporal)
+
+This package provides [Mikro ORM](https://github.com/mikro-orm/mikro-orm) types for common
+[Temporal](https://tc39.es/proposal-temporal/) objects.
+
+The library exports the following types:
+
+- `DurationType`
+- `PlainDateType`
+- `PlainDateTimeType`
+- `PlainTimeType`
+- `OffsetDateTimeType`
+
+## Installation
+
+Install via your favorite package manager:
+
+```bash
+npm install mikro-orm-temporal
+# or
+pnpm add mikro-orm-temporal
+# or
+yarn add mikro-orm-temporal
+```
+
+## Usage
+
+```ts
+import { OffsetDateTimeType } from 'mikro-orm-temporal';
+import { Entity, Property } from "@mikro-orm/core";
+
+@Entity()
+export class HelloWorld {
+    @Property({type: OffsetDateTimeType})
+    public dateTime: Temporal.ZonedDateTime;
+}
+```
+
+## Caveats
+
+Due to MikroORM not distinguishing between timestamps with and without timezone and some other quirks, this library
+makes some assumptions and decisions:
+
+- Durations are stored as `INTERVAL` in Postgres and as `INTEGER` (in seconds) on all other platforms.
+- `PlainDateTime` is stored as `VARCHAR(19)` on MSSQL, as Tedious introduces timezone issues.

package/dist/duration-type.d.ts

@@ -0,0 +1,7 @@
+import { type EntityProperty, type Platform, Type } from "@mikro-orm/core";
+export declare class DurationType extends Type<Temporal.Duration | null, string | number | null> {
+    convertToDatabaseValue(value: Temporal.Duration | null, platform: Platform): string | number | null;
+    convertToJSValue(value: string | number | null, platform: Platform): Temporal.Duration | null;
+    toJSON(value: Temporal.Duration | null): string | null;
+    getColumnType(_prop: EntityProperty, platform: Platform): string;
+}

package/dist/duration-type.js

@@ -0,0 +1,46 @@
+import { Type } from "@mikro-orm/core";
+import { isPostgres } from "./utils.js";
+export class DurationType extends Type {
+    convertToDatabaseValue(value, platform) {
+        if (value === null) {
+            return null;
+        }
+        if (isPostgres(platform)) {
+            return value.toString();
+        }
+        return value.total({ unit: "seconds" });
+    }
+    convertToJSValue(value, platform) {
+        /* node:coverage disable */
+        if (value === null) {
+            return null;
+        }
+        /* node:coverage enable */
+        if (typeof value === "number") {
+            return Temporal.Duration.from({ seconds: value });
+        }
+        if (value.startsWith("P")) {
+            return Temporal.Duration.from(value);
+        }
+        if (isPostgres(platform)) {
+            const interval = platform.convertIntervalToJSValue(value);
+            return Temporal.Duration.from(interval.toISO());
+        }
+        /* node:coverage disable */
+        throw new Error(`Unexpected interval value: ${value}`);
+        /* node:coverage enable */
+    }
+    /* node:coverage disable */
+    toJSON(value) {
+        return value ? value.toString() : null;
+    }
+    /* node:coverage enable */
+    getColumnType(_prop, platform) {
+        if (isPostgres(platform)) {
+            // Postgres has a true single-purpose column type for intervals.
+            return platform.getIntervalTypeDeclarationSQL({});
+        }
+        // For all other platforms we store the duration as integer in seconds.
+        return platform.getIntegerTypeDeclarationSQL({});
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./duration-type.js";
+export * from "./offset-date-time-type.js";
+export * from "./plain-date-time-type.js";
+export * from "./plain-date-type.js";
+export * from "./plain-time-type.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./duration-type.js";
+export * from "./offset-date-time-type.js";
+export * from "./plain-date-time-type.js";
+export * from "./plain-date-type.js";
+export * from "./plain-time-type.js";

package/dist/offset-date-time-type.d.ts

@@ -0,0 +1,8 @@
+import { type EntityProperty, type Platform, Type } from "@mikro-orm/core";
+export declare class OffsetDateTimeType extends Type<Temporal.ZonedDateTime | null, string | null> {
+    convertToDatabaseValue(value: Temporal.ZonedDateTime | null, platform: Platform): string | null;
+    convertToJSValue(value: Date | string | null, platform: Platform): Temporal.ZonedDateTime | null;
+    compareAsType(): string;
+    toJSON(value: Temporal.ZonedDateTime | null): string | null;
+    getColumnType(prop: EntityProperty, platform: Platform): string;
+}

package/dist/offset-date-time-type.js

@@ -0,0 +1,44 @@
+import { Type } from "@mikro-orm/core";
+import { isMsSql, isMySql } from "./utils.js";
+export class OffsetDateTimeType extends Type {
+    convertToDatabaseValue(value, platform) {
+        if (value === null) {
+            return null;
+        }
+        if (isMySql(platform)) {
+            // Convert to MySQL format
+            return value.withTimeZone("UTC").toPlainDateTime().toString().replace("T", " ");
+        }
+        return value.toInstant().toString();
+    }
+    convertToJSValue(value, platform) {
+        /* node:coverage disable */
+        if (value === null) {
+            return null;
+        }
+        /* node:coverage enable */
+        if (typeof value === "string") {
+            if (isMySql(platform)) {
+                // Convert to ISO format
+                return Temporal.Instant.from(`${value.replace(" ", "T")}Z`).toZonedDateTimeISO("UTC");
+            }
+            return Temporal.Instant.from(value).toZonedDateTimeISO("UTC");
+        }
+        return Temporal.Instant.fromEpochMilliseconds(value.getTime()).toZonedDateTimeISO("UTC");
+    }
+    compareAsType() {
+        return "date";
+    }
+    /* node:coverage disable */
+    toJSON(value) {
+        return value ? value.toInstant().toString() : null;
+    }
+    /* node:coverage enable */
+    getColumnType(prop, platform) {
+        if (isMsSql(platform)) {
+            // Postgres has a true single-purpose column type for timestamps with offset.
+            return "DATETIMEOFFSET";
+        }
+        return platform.getDateTimeTypeDeclarationSQL({ length: prop.length });
+    }
+}

package/dist/plain-date-time-type.d.ts

@@ -0,0 +1,8 @@
+import { type EntityProperty, type Platform, Type } from "@mikro-orm/core";
+export declare class PlainDateTimeType extends Type<Temporal.PlainDateTime | null, string | null> {
+    convertToDatabaseValue(value: Temporal.PlainDateTime | null, platform: Platform): string | null;
+    convertToJSValue(value: string | null, platform: Platform): Temporal.PlainDateTime | null;
+    compareAsType(): string;
+    toJSON(value: Temporal.PlainDateTime | null): string | null;
+    getColumnType(prop: EntityProperty, platform: Platform): string;
+}

package/dist/plain-date-time-type.js

@@ -0,0 +1,46 @@
+import { Type } from "@mikro-orm/core";
+import { isMsSql, isMySql, isPostgres } from "./utils.js";
+export class PlainDateTimeType extends Type {
+    convertToDatabaseValue(value, platform) {
+        if (value === null) {
+            return null;
+        }
+        if (isMySql(platform)) {
+            // Convert to MySQL format
+            return value.toString().replace("T", " ");
+        }
+        return value.toString();
+    }
+    convertToJSValue(value, platform) {
+        /* node:coverage disable */
+        if (value === null) {
+            return null;
+        }
+        /* node:coverage enable */
+        if (isMySql(platform)) {
+            // Convert to ISO format
+            return Temporal.PlainDateTime.from(value.replace(" ", "T"));
+        }
+        return Temporal.PlainDateTime.from(value);
+    }
+    compareAsType() {
+        return "date";
+    }
+    /* node:coverage disable */
+    toJSON(value) {
+        return value ? value.toString() : null;
+    }
+    /* node:coverage enable */
+    getColumnType(prop, platform) {
+        if (isPostgres(platform)) {
+            // Postgres has a true single-purpose column type for timestamps without timezone.
+            return "TIMESTAMP";
+        }
+        if (isMsSql(platform)) {
+            // While MSSQL does have a `datetime2` column, tedious tries to convert it to a `Date` and interprets it
+            // as local time, which causes an unwanted time shift.
+            return "VARCHAR(19)";
+        }
+        return platform.getDateTimeTypeDeclarationSQL({ length: prop.length });
+    }
+}

package/dist/plain-date-type.d.ts

@@ -0,0 +1,8 @@
+import { type EntityProperty, type Platform, Type } from "@mikro-orm/core";
+export declare class PlainDateType extends Type<Temporal.PlainDate | null, string | Date | null> {
+    convertToDatabaseValue(value: Temporal.PlainDate | null): string | null;
+    convertToJSValue(value: string | Date | null): Temporal.PlainDate | null;
+    compareAsType(): string;
+    toJSON(value: Temporal.PlainDate | null): string | null;
+    getColumnType(prop: EntityProperty, platform: Platform): string;
+}

package/dist/plain-date-type.js

@@ -0,0 +1,35 @@
+import { Type } from "@mikro-orm/core";
+export class PlainDateType extends Type {
+    convertToDatabaseValue(value) {
+        if (!value) {
+            return null;
+        }
+        return value.toString();
+    }
+    convertToJSValue(value) {
+        /* node:coverage disable */
+        if (!value) {
+            return null;
+        }
+        /* node:coverage enable */
+        if (value instanceof Date) {
+            return Temporal.PlainDate.from({
+                year: value.getFullYear(),
+                month: value.getMonth() + 1,
+                day: value.getDate(),
+            });
+        }
+        return Temporal.PlainDate.from(value);
+    }
+    compareAsType() {
+        return "string";
+    }
+    /* node:coverage disable */
+    toJSON(value) {
+        return value ? value.toString() : null;
+    }
+    /* node:coverage enable */
+    getColumnType(prop, platform) {
+        return platform.getDateTypeDeclarationSQL(prop.length);
+    }
+}

package/dist/plain-time-type.d.ts

@@ -0,0 +1,8 @@
+import { type EntityProperty, type Platform, Type } from "@mikro-orm/core";
+export declare class PlainTimeType extends Type<Temporal.PlainTime | null, string | null> {
+    convertToDatabaseValue(value: Temporal.PlainTime | null): string | null;
+    convertToJSValue(value: Date | string | null): Temporal.PlainTime | null;
+    compareAsType(): string;
+    toJSON(value: Temporal.PlainTime | null): string | null;
+    getColumnType(prop: EntityProperty, platform: Platform): string;
+}

package/dist/plain-time-type.js

@@ -0,0 +1,36 @@
+import { Type } from "@mikro-orm/core";
+export class PlainTimeType extends Type {
+    convertToDatabaseValue(value) {
+        if (value === null) {
+            return null;
+        }
+        return value.toString();
+    }
+    convertToJSValue(value) {
+        /* node:coverage disable */
+        if (value === null) {
+            return null;
+        }
+        /* node:coverage enable */
+        if (value instanceof Date) {
+            return Temporal.PlainTime.from({
+                hour: value.getHours(),
+                minute: value.getMinutes(),
+                second: value.getSeconds(),
+                millisecond: value.getMilliseconds(),
+            });
+        }
+        return Temporal.PlainTime.from(value);
+    }
+    compareAsType() {
+        return "string";
+    }
+    /* node:coverage disable */
+    toJSON(value) {
+        return value ? value.toString() : null;
+    }
+    /* node:coverage enable */
+    getColumnType(prop, platform) {
+        return platform.getTimeTypeDeclarationSQL(prop.length);
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import type { Platform } from "@mikro-orm/core";
+export declare const isPostgres: (platform: Platform) => boolean;
+export declare const isMySql: (platform: Platform) => boolean;
+export declare const isMsSql: (platform: Platform) => boolean;

package/dist/utils.js

@@ -0,0 +1,4 @@
+export const isPostgres = (platform) => platform.constructor.name === "PostgreSqlPlatform";
+export const isMySql = (platform) => platform.constructor.name === "MySqlPlatform" ||
+    platform.constructor.name === "MariaDbPlatform";
+export const isMsSql = (platform) => platform.constructor.name === "MsSqlPlatform";

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "mikro-orm-temporal",
+  "version": "1.0.0",
+  "description": "Temporal types for Mikro ORM",
+  "type": "module",
+  "author": "Ben Scholzen 'DASPRiD'",
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "temporal",
+    "mikro-orm",
+    "Interval",
+    "duration",
+    "PlainDate",
+    "PlainDateTime",
+    "PlainTime",
+    "ZonedDateTime",
+    "typescript",
+    "mysql",
+    "mariadb",
+    "postgres",
+    "mssql",
+    "sqlite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dasprid/mikro-orm-temporal.git"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "c8 tsx --test",
+    "test:ci": "c8 --reporter=lcov tsx --test",
+    "format": "biome format . --write",
+    "check": "biome check . --write"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.0.0",
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@mikro-orm/better-sqlite": "^6.4.16",
+    "@mikro-orm/core": "^6.4.16",
+    "@mikro-orm/mariadb": "^6.4.16",
+    "@mikro-orm/mssql": "^6.4.16",
+    "@mikro-orm/mysql": "^6.4.16",
+    "@mikro-orm/postgresql": "^6.4.16",
+    "@tsconfig/node22": "^22.0.2",
+    "@types/node": "^24.0.3",
+    "c8": "^10.1.3",
+    "lefthook": "^1.11.14",
+    "temporal-polyfill": "^0.3.0",
+    "temporal-spec": "^0.3.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6.0.5"
+  },
+  "packageManager": "pnpm@10.6.5+sha512.cdf928fca20832cd59ec53826492b7dc25dc524d4370b6b4adbf65803d32efaa6c1c88147c0ae4e8d579a6c9eec715757b50d4fa35eea179d868eada4ed043af",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "lefthook"
+    ]
+  }
+}