@tsgonest/types 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @tsgonest/types — Zero-runtime branded types for type-safe validation constraints.
+ *
+ * This package provides phantom branded types that the tsgonest compiler
+ * inspects at build time to generate validation and serialization code.
+ * No runtime code is emitted — these types exist purely for type safety
+ * and IDE autocomplete.
+ *
+ * @example
+ * ```ts
+ * import { tags } from "@tsgonest/types";
+ *
+ * interface CreateUserDto {
+ *   email: string & tags.Format<"email">;
+ *   name: string & tags.MinLength<1> & tags.MaxLength<255>;
+ *   age: number & tags.Minimum<0> & tags.Maximum<150>;
+ *   tags: string[] & tags.MinItems<1> & tags.UniqueItems;
+ * }
+ * ```
+ *
+ * Convenience aliases for common patterns:
+ * ```ts
+ * import { tags } from "@tsgonest/types";
+ *
+ * interface User {
+ *   email: string & tags.Email;           // same as tags.Format<"email">
+ *   id: string & tags.Uuid;               // same as tags.Format<"uuid">
+ *   website: string & tags.Url;           // same as tags.Format<"url">
+ *   age: number & tags.Int & tags.NonNegative; // int32 & >= 0
+ * }
+ * ```
+ */
+export * as tags from "./tags.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @tsgonest/types — Zero-runtime branded types for type-safe validation constraints.
+ *
+ * This package provides phantom branded types that the tsgonest compiler
+ * inspects at build time to generate validation and serialization code.
+ * No runtime code is emitted — these types exist purely for type safety
+ * and IDE autocomplete.
+ *
+ * @example
+ * ```ts
+ * import { tags } from "@tsgonest/types";
+ *
+ * interface CreateUserDto {
+ *   email: string & tags.Format<"email">;
+ *   name: string & tags.MinLength<1> & tags.MaxLength<255>;
+ *   age: number & tags.Minimum<0> & tags.Maximum<150>;
+ *   tags: string[] & tags.MinItems<1> & tags.UniqueItems;
+ * }
+ * ```
+ *
+ * Convenience aliases for common patterns:
+ * ```ts
+ * import { tags } from "@tsgonest/types";
+ *
+ * interface User {
+ *   email: string & tags.Email;           // same as tags.Format<"email">
+ *   id: string & tags.Uuid;               // same as tags.Format<"uuid">
+ *   website: string & tags.Url;           // same as tags.Format<"url">
+ *   age: number & tags.Int & tags.NonNegative; // int32 & >= 0
+ * }
+ * ```
+ */
+export * as tags from "./tags.js";

package/dist/tags.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @tsgonest/types — Zero-runtime branded types for type-safe validation constraints.
+ *
+ * These types exist purely at compile time. They produce NO runtime code.
+ * The tsgonest compiler inspects the phantom intersection properties
+ * (prefixed with `__tsgonest_`) to extract validation constraints.
+ *
+ * Usage:
+ *   import { tags } from "@tsgonest/types";
+ *
+ *   interface CreateUserDto {
+ *     email: string & tags.Format<"email">;
+ *     name: string & tags.MinLength<1> & tags.MaxLength<255>;
+ *     age: number & tags.Minimum<0> & tags.Maximum<150>;
+ *   }
+ *
+ * This is equivalent to using JSDoc tags:
+ *   interface CreateUserDto {
+ *     // @format email
+ *     email: string;
+ *     // @minLength 1
+ *     // @maxLength 255
+ *     name: string;
+ *     // @minimum 0
+ *     // @maximum 150
+ *     age: number;
+ *   }
+ */
+/**
+ * All supported string format values.
+ * Includes standard JSON Schema formats, plus Zod 4 / typia extras.
+ */
+export type FormatValue = "email" | "idn-email" | "url" | "uri" | "uri-reference" | "uri-template" | "iri" | "iri-reference" | "uuid" | "ipv4" | "ipv6" | "hostname" | "idn-hostname" | "date-time" | "date" | "time" | "duration" | "json-pointer" | "relative-json-pointer" | "byte" | "password" | "regex" | "nanoid" | "cuid" | "cuid2" | "ulid" | "jwt" | "base64url" | "hex" | "mac" | "cidrv4" | "cidrv6" | "emoji";
+/**
+ * Constrain a string to match a specific format (e.g. "email", "uuid", "url").
+ *
+ * @example
+ *   type Email = string & tags.Format<"email">;
+ *   type UserId = string & tags.Format<"uuid">;
+ */
+export type Format<F extends FormatValue> = {
+    readonly __tsgonest_format: F;
+};
+/**
+ * Constrain minimum string length.
+ *
+ * @example
+ *   type NonEmpty = string & tags.MinLength<1>;
+ */
+export type MinLength<N extends number> = {
+    readonly __tsgonest_minLength: N;
+};
+/**
+ * Constrain maximum string length.
+ *
+ * @example
+ *   type ShortName = string & tags.MaxLength<50>;
+ */
+export type MaxLength<N extends number> = {
+    readonly __tsgonest_maxLength: N;
+};
+/**
+ * Constrain string to exact length (sets both minLength and maxLength).
+ *
+ * @example
+ *   type CountryCode = string & tags.Length<2>;
+ */
+export type Length<N extends number> = MinLength<N> & MaxLength<N>;
+/**
+ * Constrain a string to match a regex pattern.
+ *
+ * @example
+ *   type AlphaNumeric = string & tags.Pattern<"^[a-zA-Z0-9]+$">;
+ */
+export type Pattern<P extends string> = {
+    readonly __tsgonest_pattern: P;
+};
+/**
+ * Constrain a string to start with a specific prefix.
+ *
+ * @example
+ *   type HttpUrl = string & tags.StartsWith<"https://">;
+ */
+export type StartsWith<S extends string> = {
+    readonly __tsgonest_startsWith: S;
+};
+/**
+ * Constrain a string to end with a specific suffix.
+ *
+ * @example
+ *   type JsonFile = string & tags.EndsWith<".json">;
+ */
+export type EndsWith<S extends string> = {
+    readonly __tsgonest_endsWith: S;
+};
+/**
+ * Constrain a string to include a specific substring.
+ *
+ * @example
+ *   type ContainsAt = string & tags.Includes<"@">;
+ */
+export type Includes<S extends string> = {
+    readonly __tsgonest_includes: S;
+};
+/**
+ * Constrain minimum numeric value (inclusive).
+ *
+ * @example
+ *   type NonNegative = number & tags.Minimum<0>;
+ */
+export type Minimum<N extends number> = {
+    readonly __tsgonest_minimum: N;
+};
+/**
+ * Constrain maximum numeric value (inclusive).
+ *
+ * @example
+ *   type Percentage = number & tags.Minimum<0> & tags.Maximum<100>;
+ */
+export type Maximum<N extends number> = {
+    readonly __tsgonest_maximum: N;
+};
+/**
+ * Constrain exclusive minimum (value must be > N).
+ *
+ * @example
+ *   type Positive = number & tags.ExclusiveMinimum<0>;
+ */
+export type ExclusiveMinimum<N extends number> = {
+    readonly __tsgonest_exclusiveMinimum: N;
+};
+/**
+ * Constrain exclusive maximum (value must be < N).
+ *
+ * @example
+ *   type Negative = number & tags.ExclusiveMaximum<0>;
+ */
+export type ExclusiveMaximum<N extends number> = {
+    readonly __tsgonest_exclusiveMaximum: N;
+};
+/**
+ * Constrain numeric value to be a multiple of N.
+ *
+ * @example
+ *   type Even = number & tags.MultipleOf<2>;
+ */
+export type MultipleOf<N extends number> = {
+    readonly __tsgonest_multipleOf: N;
+};
+/** Valid numeric type values. */
+export type NumericTypeValue = "int32" | "uint32" | "int64" | "uint64" | "float" | "double";
+/**
+ * Constrain a number to a specific numeric type (range/precision).
+ *
+ * @example
+ *   type Port = number & tags.Type<"uint32">;
+ *   type SafeInt = number & tags.Type<"int64">;
+ */
+export type Type<T extends NumericTypeValue> = {
+    readonly __tsgonest_type: T;
+};
+/**
+ * Constrain minimum array length.
+ *
+ * @example
+ *   type NonEmptyArray<T> = T[] & tags.MinItems<1>;
+ */
+export type MinItems<N extends number> = {
+    readonly __tsgonest_minItems: N;
+};
+/**
+ * Constrain maximum array length.
+ *
+ * @example
+ *   type LimitedArray<T> = T[] & tags.MaxItems<100>;
+ */
+export type MaxItems<N extends number> = {
+    readonly __tsgonest_maxItems: N;
+};
+/**
+ * Constrain array items to be unique.
+ *
+ * @example
+ *   type UniqueIds = string[] & tags.UniqueItems;
+ */
+export type UniqueItems = {
+    readonly __tsgonest_uniqueItems: true;
+};
+/** String validated as email format. */
+export type Email = Format<"email">;
+/** String validated as UUID format. */
+export type Uuid = Format<"uuid">;
+/** String validated as URL format. */
+export type Url = Format<"url">;
+/** String validated as URI format. */
+export type Uri = Format<"uri">;
+/** String validated as IPv4 format. */
+export type IPv4 = Format<"ipv4">;
+/** String validated as IPv6 format. */
+export type IPv6 = Format<"ipv6">;
+/** String validated as date-time (ISO 8601) format. */
+export type DateTime = Format<"date-time">;
+/** String validated as date (YYYY-MM-DD) format. */
+export type DateOnly = Format<"date">;
+/** String validated as time (HH:MM:SS) format. */
+export type Time = Format<"time">;
+/** String validated as duration (ISO 8601 duration) format. */
+export type Duration = Format<"duration">;
+/** String validated as JWT format. */
+export type Jwt = Format<"jwt">;
+/** String validated as ULID format. */
+export type Ulid = Format<"ulid">;
+/** String validated as CUID format. */
+export type Cuid = Format<"cuid">;
+/** String validated as CUID2 format. */
+export type Cuid2 = Format<"cuid2">;
+/** String validated as Nano ID format. */
+export type NanoId = Format<"nanoid">;
+/** Number constrained to be > 0. */
+export type Positive = ExclusiveMinimum<0>;
+/** Number constrained to be < 0. */
+export type Negative = ExclusiveMaximum<0>;
+/** Number constrained to be >= 0. */
+export type NonNegative = Minimum<0>;
+/** Number constrained to be <= 0. */
+export type NonPositive = Maximum<0>;
+/** Number constrained to 32-bit integer range. */
+export type Int = Type<"int32">;
+/** Number constrained to JS safe integer range (-2^53+1 to 2^53-1). */
+export type SafeInt = Type<"int64">;
+/** Number constrained to finite values (no Infinity/NaN). */
+export type Finite = Type<"float">;
+/** Number constrained to 32-bit unsigned integer range. */
+export type Uint = Type<"uint32">;
+/** Number constrained to double precision float. */
+export type Double = Type<"double">;
+//# sourceMappingURL=tags.d.ts.map

package/dist/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"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"}

package/dist/tags.js

@@ -0,0 +1,29 @@
+/**
+ * @tsgonest/types — Zero-runtime branded types for type-safe validation constraints.
+ *
+ * These types exist purely at compile time. They produce NO runtime code.
+ * The tsgonest compiler inspects the phantom intersection properties
+ * (prefixed with `__tsgonest_`) to extract validation constraints.
+ *
+ * Usage:
+ *   import { tags } from "@tsgonest/types";
+ *
+ *   interface CreateUserDto {
+ *     email: string & tags.Format<"email">;
+ *     name: string & tags.MinLength<1> & tags.MaxLength<255>;
+ *     age: number & tags.Minimum<0> & tags.Maximum<150>;
+ *   }
+ *
+ * This is equivalent to using JSDoc tags:
+ *   interface CreateUserDto {
+ *     // @format email
+ *     email: string;
+ *     // @minLength 1
+ *     // @maxLength 255
+ *     name: string;
+ *     // @minimum 0
+ *     // @maximum 150
+ *     age: number;
+ *   }
+ */
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tsgonest/types",
+  "version": "0.0.1",
+  "description": "Zero-runtime branded types for tsgonest validation constraints — type-safe alternative to JSDoc tags",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./tags": {
+      "types": "./dist/tags.d.ts",
+      "import": "./dist/tags.mjs",
+      "require": "./dist/tags.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "typescript",
+    "validation",
+    "branded-types",
+    "phantom-types",
+    "tsgonest",
+    "type-safe"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsgonest/tsgonest"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit"
+  }
+}