@hexaijs/contracts 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @hexaijs/contracts
+
+> Zero-dependency marker decorators and base message classes for hexai contract definitions
+
+## Overview
+
+`@hexaijs/contracts` provides the foundational contract types used across hexai:
+
+- **Command** and **Query** base classes with typed payload and result
+- **Decorator markers** (`@PublicEvent`, `@PublicCommand`, `@PublicQuery`) for static analysis by the contracts generator
+
+This package has no runtime dependencies beyond `@hexaijs/core` as a peer dependency.
+
+## Installation
+
+```bash
+npm install @hexaijs/contracts
+```
+
+## Core Exports
+
+### Command and Query
+
+Base classes for CQRS messages. Both accept two type parameters:
+
+```typescript
+import { Command, Query } from "@hexaijs/contracts";
+
+class CreateOrderCommand extends Command<
+    { customerId: string; items: Item[] },  // Payload
+    { orderId: string }                     // ResultType
+> {
+    static readonly type = "order.create-order";
+}
+
+class GetOrderQuery extends Query<
+    { orderId: string },  // Payload
+    OrderDto              // ResultType
+> {
+    static readonly type = "order.get-order";
+}
+```
+
+`Command` and `Query` extend `Message<Payload>` from `@hexaijs/core`, adding a phantom `ResultType` property for TypeScript type inference.
+
+### Decorators (`@hexaijs/contracts/decorators`)
+
+Pure no-op markers used by `@hexaijs/plugin-contracts-generator` for static analysis. They have no runtime effect.
+
+```typescript
+import { PublicCommand, PublicEvent, PublicQuery } from "@hexaijs/contracts/decorators";
+
+@PublicCommand()
+class CreateOrderCommand extends Command<CreateOrderPayload, CreateOrderResult> { ... }
+
+@PublicEvent({ version: 2 })
+class OrderPlaced extends DomainEvent<OrderPlacedPayload> { ... }
+
+@PublicQuery({ response: "UserProfile" })
+class GetUserQuery extends Query<{ userId: string }, UserProfile> { ... }
+```
+
+#### Decorator Options
+
+| Decorator | Options |
+|-----------|---------|
+| `@PublicEvent(options?)` | `version?: number` — event version; `context?: string` — business context (inferred from package) |
+| `@PublicCommand(options?)` | `context?: string` — business context; `response?: string` — explicit response type name |
+| `@PublicQuery(options?)` | `context?: string` — business context; `response?: string` — explicit response type name |
+
+## API Highlights
+
+| Export | Subpath | Description |
+|--------|---------|-------------|
+| `Command<P, O>` | `.` | Base class for commands with payload and output type |
+| `Query<P, O>` | `.` | Base class for queries with payload and output type |
+| `PublicEvent` | `./decorators` | No-op marker for domain events |
+| `PublicCommand` | `./decorators` | No-op marker for commands |
+| `PublicQuery` | `./decorators` | No-op marker for queries |
+
+## See Also
+
+- [@hexaijs/application](../application/README.md) — Application layer that consumes these contracts
+- [@hexaijs/plugin-contracts-generator](../plugin-contracts-generator/README.md) — Generates frontend-compatible types from decorated classes

package/dist/decorators/index.d.ts

@@ -0,0 +1,46 @@
+interface PublicEventOptions {
+    /**
+     * Event version for versioned events
+     * @example @PublicEvent({ version: 2 })
+     */
+    version?: number;
+    /**
+     * Business context this event belongs to.
+     * If not specified, inferred from package name.
+     * @example @PublicEvent({ context: 'lecture' })
+     */
+    context?: string;
+}
+interface PublicCommandOptions {
+    /**
+     * Business context this command belongs to.
+     * If not specified, inferred from package name.
+     * @example @PublicCommand({ context: 'auth' })
+     */
+    context?: string;
+    /**
+     * Explicit response type name for this command.
+     * If specified, the parser will look for this type in the same file.
+     * @example @PublicCommand({ response: 'CreateUserResult' })
+     */
+    response?: string;
+}
+interface PublicQueryOptions {
+    /**
+     * Business context this query belongs to.
+     * If not specified, inferred from package name.
+     * @example @PublicQuery({ context: 'catalog' })
+     */
+    context?: string;
+    /**
+     * Explicit response type name for this query.
+     * If specified, the parser will look for this type in the same file.
+     * @example @PublicQuery({ response: 'UserProfile' })
+     */
+    response?: string;
+}
+declare function PublicEvent(_options?: PublicEventOptions): ClassDecorator;
+declare function PublicCommand(_options?: PublicCommandOptions): ClassDecorator;
+declare function PublicQuery(_options?: PublicQueryOptions): ClassDecorator;
+
+export { PublicCommand, type PublicCommandOptions, PublicEvent, type PublicEventOptions, PublicQuery, type PublicQueryOptions };

package/dist/decorators/index.js

@@ -0,0 +1,14 @@
+// src/decorators/index.ts
+function PublicEvent(_options = {}) {
+  return (target) => target;
+}
+function PublicCommand(_options = {}) {
+  return (target) => target;
+}
+function PublicQuery(_options = {}) {
+  return (target) => target;
+}
+
+export { PublicCommand, PublicEvent, PublicQuery };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/decorators/index.ts"],"names":[],"mappings":";AA+CO,SAAS,WAAA,CAAY,QAAA,GAA+B,EAAC,EAAmB;AAC7E,EAAA,OAAO,CAAC,MAAA,KAAW,MAAA;AACrB;AAEO,SAAS,aAAA,CACd,QAAA,GAAiC,EAAC,EAClB;AAChB,EAAA,OAAO,CAAC,MAAA,KAAW,MAAA;AACrB;AAEO,SAAS,WAAA,CAAY,QAAA,GAA+B,EAAC,EAAmB;AAC7E,EAAA,OAAO,CAAC,MAAA,KAAW,MAAA;AACrB","file":"index.js","sourcesContent":["export interface PublicEventOptions {\n  /**\n   * Event version for versioned events\n   * @example @PublicEvent({ version: 2 })\n   */\n  version?: number;\n\n  /**\n   * Business context this event belongs to.\n   * If not specified, inferred from package name.\n   * @example @PublicEvent({ context: 'lecture' })\n   */\n  context?: string;\n}\n\nexport interface PublicCommandOptions {\n  /**\n   * Business context this command belongs to.\n   * If not specified, inferred from package name.\n   * @example @PublicCommand({ context: 'auth' })\n   */\n  context?: string;\n\n  /**\n   * Explicit response type name for this command.\n   * If specified, the parser will look for this type in the same file.\n   * @example @PublicCommand({ response: 'CreateUserResult' })\n   */\n  response?: string;\n}\n\nexport interface PublicQueryOptions {\n  /**\n   * Business context this query belongs to.\n   * If not specified, inferred from package name.\n   * @example @PublicQuery({ context: 'catalog' })\n   */\n  context?: string;\n\n  /**\n   * Explicit response type name for this query.\n   * If specified, the parser will look for this type in the same file.\n   * @example @PublicQuery({ response: 'UserProfile' })\n   */\n  response?: string;\n}\n\nexport function PublicEvent(_options: PublicEventOptions = {}): ClassDecorator {\n  return (target) => target;\n}\n\nexport function PublicCommand(\n  _options: PublicCommandOptions = {}\n): ClassDecorator {\n  return (target) => target;\n}\n\nexport function PublicQuery(_options: PublicQueryOptions = {}): ClassDecorator {\n  return (target) => target;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { PublicCommand, PublicCommandOptions, PublicEvent, PublicEventOptions, PublicQuery, PublicQueryOptions } from './decorators/index.js';
+import { Message } from '@hexaijs/core';
+
+declare class Command<Payload = unknown, ResultType = unknown> extends Message<Payload> {
+    readonly ResultType: ResultType;
+    static getIntent(): string;
+}
+
+declare class Query<Payload = unknown, ResultType = unknown> extends Message<Payload> {
+    readonly ResultType: ResultType;
+    static getIntent(): string;
+}
+
+export { Command, Query };

package/dist/index.js

@@ -0,0 +1,26 @@
+import { Message } from '@hexaijs/core';
+
+// src/decorators/index.ts
+function PublicEvent(_options = {}) {
+  return (target) => target;
+}
+function PublicCommand(_options = {}) {
+  return (target) => target;
+}
+function PublicQuery(_options = {}) {
+  return (target) => target;
+}
+var Command = class extends Message {
+  static getIntent() {
+    return "command";
+  }
+};
+var Query = class extends Message {
+  static getIntent() {
+    return "query";
+  }
+};
+
+export { Command, PublicCommand, PublicEvent, PublicQuery, Query };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/decorators/index.ts","../src/command.ts","../src/query.ts"],"names":["Message"],"mappings":";;;AA+CO,SAAS,WAAA,CAAY,QAAA,GAA+B,EAAC,EAAmB;AAC7E,EAAA,OAAO,CAAC,MAAA,KAAW,MAAA;AACrB;AAEO,SAAS,aAAA,CACd,QAAA,GAAiC,EAAC,EAClB;AAChB,EAAA,OAAO,CAAC,MAAA,KAAW,MAAA;AACrB;AAEO,SAAS,WAAA,CAAY,QAAA,GAA+B,EAAC,EAAmB;AAC7E,EAAA,OAAO,CAAC,MAAA,KAAW,MAAA;AACrB;ACzDO,IAAM,OAAA,GAAN,cAA+D,OAAA,CAAiB;AAAA,EAGnF,OAAgB,SAAA,GAAoB;AAChC,IAAA,OAAO,SAAA;AAAA,EACX;AACJ;ACNO,IAAM,KAAA,GAAN,cAA6DA,OAAAA,CAAiB;AAAA,EAGjF,OAAgB,SAAA,GAAoB;AAChC,IAAA,OAAO,OAAA;AAAA,EACX;AACJ","file":"index.js","sourcesContent":["export interface PublicEventOptions {\n  /**\n   * Event version for versioned events\n   * @example @PublicEvent({ version: 2 })\n   */\n  version?: number;\n\n  /**\n   * Business context this event belongs to.\n   * If not specified, inferred from package name.\n   * @example @PublicEvent({ context: 'lecture' })\n   */\n  context?: string;\n}\n\nexport interface PublicCommandOptions {\n  /**\n   * Business context this command belongs to.\n   * If not specified, inferred from package name.\n   * @example @PublicCommand({ context: 'auth' })\n   */\n  context?: string;\n\n  /**\n   * Explicit response type name for this command.\n   * If specified, the parser will look for this type in the same file.\n   * @example @PublicCommand({ response: 'CreateUserResult' })\n   */\n  response?: string;\n}\n\nexport interface PublicQueryOptions {\n  /**\n   * Business context this query belongs to.\n   * If not specified, inferred from package name.\n   * @example @PublicQuery({ context: 'catalog' })\n   */\n  context?: string;\n\n  /**\n   * Explicit response type name for this query.\n   * If specified, the parser will look for this type in the same file.\n   * @example @PublicQuery({ response: 'UserProfile' })\n   */\n  response?: string;\n}\n\nexport function PublicEvent(_options: PublicEventOptions = {}): ClassDecorator {\n  return (target) => target;\n}\n\nexport function PublicCommand(\n  _options: PublicCommandOptions = {}\n): ClassDecorator {\n  return (target) => target;\n}\n\nexport function PublicQuery(_options: PublicQueryOptions = {}): ClassDecorator {\n  return (target) => target;\n}\n","import { Message } from \"@hexaijs/core\";\n\nexport class Command<Payload = unknown, ResultType = unknown> extends Message<Payload> {\n    declare readonly ResultType: ResultType;\n\n    static override getIntent(): string {\n        return \"command\";\n    }\n}\n","import { Message } from \"@hexaijs/core\";\n\nexport class Query<Payload = unknown, ResultType = unknown> extends Message<Payload> {\n    declare readonly ResultType: ResultType;\n\n    static override getIntent(): string {\n        return \"query\";\n    }\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@hexaijs/contracts",
+    "publishConfig": {
+        "access": "public"
+    },
+    "version": "0.1.0",
+    "type": "module",
+    "description": "Zero-dependency marker decorators for hexai contract definitions",
+    "license": "MIT",
+    "author": "Sangwoo Hyun <wkdny.hyun@gmail.com>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/workingdanny911/hexai.git",
+        "directory": "packages/contracts"
+    },
+    "homepage": "https://github.com/workingdanny911/hexai#readme",
+    "bugs": {
+        "url": "https://github.com/workingdanny911/hexai/issues"
+    },
+    "keywords": [
+        "hexai",
+        "hexagonal",
+        "clean-architecture",
+        "ddd",
+        "contracts",
+        "decorators",
+        "typescript"
+    ],
+    "files": [
+        "dist",
+        "LICENSE"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./decorators": {
+            "types": "./dist/decorators/index.d.ts",
+            "import": "./dist/decorators/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "build": "tsup"
+    },
+    "peerDependencies": {
+        "@hexaijs/core": "^0.6.0"
+    },
+    "devDependencies": {
+        "@hexaijs/core": "workspace:^",
+        "@hexaijs/tooling": "workspace:*"
+    }
+}