@nxgt/typespec 0.1.0

package/lib/headers.tsp

@@ -0,0 +1,76 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * The `Idempotency-Key` a client may send with a write, 1 to 255 characters.
+ * Spread it into an operation's parameters.
+ */
+model IdempotencyKeyHeader {
+  /**
+   * Made up by the client, once per write it means, and sent again with every
+   * retry of that write: the write happens once, and a retry gets the first
+   * answer back. Without it, every request writes.
+   */
+  @header("Idempotency-Key")
+  @minLength(1)
+  @maxLength(255)
+  idempotencyKey?: string;
+}
+
+/** `Idempotent-Replayed`, on a reply to a request with an `Idempotency-Key`. */
+model IdempotentReplayedHeader {
+  /**
+   * `true` when this answer is the one an earlier request with the same
+   * `Idempotency-Key` got, and nothing was written this time.
+   */
+  @header("Idempotent-Replayed")
+  idempotentReplayed?: "true";
+}
+
+/** The `RateLimit-*` headers of a rate-limited route's replies. */
+model RateLimitHeaders {
+  /** How many requests a full window allows. */
+  @header("RateLimit-Limit")
+  rateLimitLimit?: integer;
+
+  /** How many more requests are allowed now, after this one. */
+  @header("RateLimit-Remaining")
+  rateLimitRemaining?: integer;
+
+  /** Seconds until the window is full again, rounded up. */
+  @header("RateLimit-Reset")
+  rateLimitReset?: integer;
+}
+
+/** `Retry-After`, in seconds. */
+model RetryAfterHeader {
+  /** Seconds to wait before trying again, rounded up: a delay, never a date. */
+  @header("Retry-After")
+  retryAfter?: integer;
+}
+
+/**
+ * A request with this `Idempotency-Key` is still running. Retry it as it is,
+ * after `Retry-After`.
+ */
+@error
+model IdempotencyInProgress {
+  @statusCode _: 409;
+  ...RateLimitHeaders;
+  ...RetryAfterHeader;
+  @body body: ConflictBody;
+}
+
+/**
+ * This `Idempotency-Key` was already used for a request with another body. A
+ * new request takes a new key.
+ */
+@error
+model IdempotencyKeyReused {
+  @statusCode _: 422;
+  ...RateLimitHeaders;
+  @body body: UnprocessableEntityBody;
+}

package/lib/main.tsp

@@ -0,0 +1,11 @@
+// The library's JavaScript: its name, diagnostics and decorators, built from
+// src/ into dist/.
+import "../dist/index.js";
+import "./errors.tsp";
+import "./operation-ids.tsp";
+import "./pagination.tsp";
+import "./auth.tsp";
+import "./scalars.tsp";
+import "./columns.tsp";
+import "./headers.tsp";
+import "./resources.tsp";

package/lib/operation-ids.tsp

@@ -0,0 +1,22 @@
+import "@typespec/openapi";
+
+using TypeSpec.Reflection;
+
+namespace Nxgt;
+
+/**
+ * Names each operation of the interface after its method and the interface,
+ * `<operation><Interface>`: `list` in `interface Pets` becomes `listPets`. An
+ * operation with its own `@operationId` keeps it. An interface extending a
+ * marked one, or an instance of a marked template, is named after itself. An
+ * id another operation has is an error, `duplicate-operation-id`.
+ *
+ * @example
+ * ```typespec
+ * @operationIds
+ * interface Pets {
+ *   @get list(): Pet[];
+ * }
+ * ```
+ */
+extern dec operationIds(target: Interface);

package/lib/pagination.tsp

@@ -0,0 +1,62 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * The query of an offset page, as `@nxgt/drizzle` and `@nxgt/mongo` read it.
+ * Spread it into an operation's parameters.
+ */
+model PageParameters {
+  /** 1-based. */
+  @query
+  @minValue(1)
+  page?: integer = 1;
+
+  /** How many items a page holds. A server lowers one above its maximum to it. */
+  @query
+  @minValue(1)
+  pageSize?: integer = 20;
+}
+
+/** One page of an offset pagination. */
+@friendlyName("{name}Page", Item)
+model Page<Item> {
+  items: Item[];
+
+  /** Every item that matches, across all pages. */
+  total: integer;
+
+  /** 1-based. */
+  page: integer;
+
+  pageSize: integer;
+
+  /** `ceil(total / pageSize)`: 0 when nothing matches. */
+  pageCount: integer;
+}
+
+/**
+ * The query of a cursor page, as `@nxgt/drizzle` and `@nxgt/mongo` read it.
+ * Spread it into an operation's parameters.
+ */
+model CursorPageParameters {
+  /** The previous page's `nextCursor`; absent for the first page. */
+  @query
+  after?: string;
+
+  /** How many items a page holds. A server lowers one above its maximum to it. */
+  @query
+  @minValue(1)
+  limit?: integer = 20;
+}
+
+/** One page of a cursor pagination, which gives no total. */
+@friendlyName("{name}CursorPage", Item)
+model CursorPage<Item> {
+  items: Item[];
+
+  /** Pass it as `after` for the next page; `null` on the last one. */
+  nextCursor: string | null;
+}

package/lib/resources.tsp

@@ -0,0 +1,63 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * The sort of a list, as `@nxgt/drizzle` takes it: one field, and a
+ * direction. `Field` is the union of the fields a client may sort by.
+ * Spread it into an operation's parameters.
+ */
+model SortParameters<Field extends string> {
+  /** The field to sort by. */
+  @query
+  orderBy?: Field;
+
+  /** `asc` or `desc`. */
+  @query
+  direction?: "asc" | "desc" = "asc";
+}
+
+/**
+ * The five operations of a resource, at `/<route>` and `/<route>/{id}`:
+ * `list` pages by offset, with the `Filters` the spec writes and a sort by
+ * `SortField`; `read`, `create`, `update` (a merge patch) and `delete`.
+ * Extend it with `@route`; `@operationIds` names the operations after the
+ * interface that extends it: `listPosts`, `readPosts`…
+ *
+ * @template Item The resource's model.
+ * @template Filters A model of `@query` properties, spread into `list`.
+ * @template SortField The fields `list` may sort by; `"id"` by default.
+ * @template Id The type of `{id}`; `uuid` by default.
+ */
+@operationIds
+interface Resource<
+  Item extends {},
+  Filters extends {} = {},
+  SortField extends string = "id",
+  Id = uuid
+> {
+  /** One page of the resources, filtered and sorted. */
+  @get
+  list(...Filters, ...PageParameters, ...SortParameters<SortField>): Page<Item>;
+
+  /** One resource. */
+  @get
+  read(@path id: Id): Item | NotFound;
+
+  /** Creates a resource. */
+  @post
+  create(@body item: Create<Item>): {
+    @statusCode _: 201;
+    @body item: Item;
+  } | BadRequest | Conflict;
+
+  /** Updates a resource with a merge patch. */
+  @patch
+  update(@path id: Id, @body item: MergePatchUpdate<Item>): Item | BadRequest | NotFound | Conflict;
+
+  /** Deletes a resource. */
+  @delete
+  delete(@path id: Id): NoContentResponse | NotFound;
+}

package/lib/scalars.tsp

@@ -0,0 +1,12 @@
+namespace Nxgt;
+
+// The id @nxgt/drizzle's id() and actors() columns hold by default.
+/** A UUID, such as `0b8e5c1e-2f4a-4c3b-9d6e-7f8a9b0c1d2e`. */
+@friendlyName("Uuid")
+@format("uuid")
+scalar uuid extends string;
+
+/** An e-mail address. */
+@friendlyName("Email")
+@format("email")
+scalar email extends string;

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@nxgt/typespec",
+	"version": "0.1.0",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"tspMain": "./lib/main.tsp",
+	"files": [
+		"dist",
+		"lib",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"typespec": "./lib/main.tsp",
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-http.git",
+		"directory": "packages/typespec"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"fixtures": "bun run test/generate.ts",
+		"test": "bun run fixtures && bun test src",
+		"typecheck": "bun run fixtures && tsc --noEmit",
+		"fixtures:typespec": "bun run test/generate.ts --accept"
+	},
+	"nxgt": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@typespec/compiler": "^1.16.0",
+		"@typespec/http": "^1.16.0",
+		"@typespec/openapi": "^1.16.0",
+		"typescript": "^6.0.3"
+	},
+	"devDependencies": {
+		"@nxgt/openapi-codegen": "^0.5.0",
+		"@nxgt/openapi-hono": "^0.3.0",
+		"@types/bun": "^1.4.0",
+		"@typespec/compiler": "1.16.0",
+		"@typespec/http": "1.16.0",
+		"@typespec/openapi": "1.16.0",
+		"@typespec/openapi3": "1.16.0",
+		"hono": "^4.13.4",
+		"zod": "^4.5.4"
+	}
+}