@colspec/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Om Prakash Das
+
+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

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @colspec/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Store, version and serve [colspec](https://github.com/Om1938/colspec) table
+definitions from your own backend. It works with any database and any Node.js
+framework, and needs no ORM or separate service.
+
+```sh
+npm install @colspec/server @colspec/core
+```
+
+## 1. Implement storage
+
+One row or document per revision, unique by `(tableId, revision)`.
+
+```ts
+import type { TableDefinitionRepository } from "@colspec/server";
+
+const repository: TableDefinitionRepository = {
+  find: (tableId, revision) => /* one record or undefined */,
+  findLatest: (tableId, status) => /* highest revision with that status */,
+  list: (tableId) => /* all revisions, oldest first */,
+  save: (record) => /* insert or replace */,
+};
+```
+
+`createMemoryRepository()` is included for tests and prototypes.
+
+## 2. Manage definitions
+
+```ts
+import { createTableDefinitionService } from "@colspec/server";
+
+const definitions = createTableDefinitionService(repository);
+
+await definitions.saveDraft(json); // validates; throws ContractError if invalid
+await definitions.publish("crm.contacts", 4);
+await definitions.getPublished("crm.contacts"); // latest published revision
+await definitions.listRevisions("crm.contacts");
+```
+
+Drafts can be saved repeatedly. A published revision is immutable; change a
+table by saving a new revision number.
+
+## 3. Serve them
+
+`getDefinitionResponse` returns `{ status, headers, body }` with an `ETag` and
+`304 Not Modified` handling.
+
+```ts
+app.get("/api/table-definitions/:tableId", async (req, res) => {
+  const { status, headers, body } = await getDefinitionResponse(definitions, {
+    tableId: req.params.tableId,
+    ifNoneMatch: req.get("if-none-match"),
+  });
+  res.status(status).set(headers).json(body);
+});
+```
+
+## 4. Accept sort and filter requests safely
+
+Clients send operation keys, not field names. Map every key through a list
+you control.
+
+```ts
+import { resolveServerQuery } from "@colspec/server";
+
+const result = resolveServerQuery(untrustedJson, {
+  "contact.created_at": "contacts.created_at",
+  status: "contacts.status",
+});
+
+if (!result.ok) return badRequest(result.diagnostics);
+const { sort, filters, page } = result.value; // only fields from your list
+```
+
+Malformed input and unlisted keys are rejected. Filter _values_ are still
+untrusted: validate or coerce them before they reach a query.
+
+## Not included
+
+Authentication and authorization. Decide in your application who may save,
+publish and read definitions.
+
+[Documentation](https://github.com/Om1938/colspec/tree/main/apps/docs/guide) ·
+[NestJS + MongoDB example](https://github.com/Om1938/colspec/tree/main/examples) · MIT

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+import { Result, ServerQuery, TableContract, ValidateOptions } from "@colspec/core";
+//#region src/repository.d.ts
+export type DefinitionStatus = "draft" | "published";
+/** One stored revision of a table definition; unique by `(tableId, revision)`. */
+export interface TableDefinitionRecord {
+  tableId: string;
+  revision: number;
+  schemaVersion: string;
+  definition: TableContract;
+  status: DefinitionStatus;
+  createdAt: Date;
+  updatedAt: Date;
+}
+/**
+ * The storage boundary. Implement it over any database: one row or document
+ * per revision, with the contract kept as JSON.
+ */
+export interface TableDefinitionRepository {
+  find(tableId: string, revision: number): Promise<TableDefinitionRecord | undefined>;
+  /** The highest revision with the given status. */
+  findLatest(tableId: string, status: DefinitionStatus): Promise<TableDefinitionRecord | undefined>;
+  /** Every revision of a table, oldest first. */
+  list(tableId: string): Promise<TableDefinitionRecord[]>;
+  /** Inserts the record, or replaces the one with the same `(tableId, revision)`. */
+  save(record: TableDefinitionRecord): Promise<void>;
+}
+//#endregion
+//#region src/service.d.ts
+export declare class DefinitionNotFoundError extends Error {
+  constructor(tableId: string, revision?: number);
+}
+export declare class RevisionPublishedError extends Error {
+  constructor(tableId: string, revision: number);
+}
+export interface ServiceOptions {
+  /** Passed to `validateContract` for every definition the service handles. */
+  validation?: ValidateOptions;
+  now?: () => Date;
+}
+export interface TableDefinitionService {
+  validate(input: unknown): Result<TableContract>;
+  /** Stores a draft. Throws `ContractError` if invalid, `RevisionPublishedError` if published. */
+  saveDraft(input: unknown): Promise<TableDefinitionRecord>;
+  /** Makes a draft visible to consumers and freezes it. Publishing twice is a no-op. */
+  publish(tableId: string, revision: number): Promise<TableDefinitionRecord>;
+  /** The latest published revision, or a specific one. Drafts are never returned. */
+  getPublished(tableId: string, revision?: number): Promise<TableDefinitionRecord | undefined>;
+  listRevisions(tableId: string): Promise<TableDefinitionRecord[]>;
+}
+/** The definition lifecycle on top of any storage implementation. */
+export declare function createTableDefinitionService(repository: TableDefinitionRepository, { validation, now }?: ServiceOptions): TableDefinitionService;
+//#endregion
+//#region src/http.d.ts
+/** Published revisions never change, so identity plus revision is a strong validator. */
+export declare function etagFor({ tableId, revision }: Pick<TableDefinitionRecord, "tableId" | "revision">): string;
+/** A response any HTTP framework can send: status, headers and a JSON body. */
+export interface DefinitionResponse {
+  status: 200 | 304 | 404;
+  headers: Record<string, string>;
+  body?: TableContract | {
+    error: string;
+  };
+}
+export interface DefinitionRequest {
+  tableId: string;
+  revision?: number;
+  /** The request's `If-None-Match` header, if any. */
+  ifNoneMatch?: string | null;
+}
+/**
+ * Answers a contract retrieval request, including conditional requests, so
+ * clients revalidate with a 304 instead of downloading an unchanged contract.
+ */
+export declare function getDefinitionResponse(service: TableDefinitionService, { tableId, revision, ifNoneMatch }: DefinitionRequest): Promise<DefinitionResponse>;
+//#endregion
+//#region src/memory-repository.d.ts
+/** A repository held in memory, for tests, examples and prototypes. */
+export declare function createMemoryRepository(): TableDefinitionRepository;
+//#endregion
+//#region src/server-query.d.ts
+/** A client's query with every key replaced by its approved backend field. */
+export interface ResolvedQuery<TField> {
+  sort: Array<{
+    field: TField;
+    desc: boolean;
+  }>;
+  filters: Array<{
+    field: TField;
+    value: unknown;
+  }>;
+  page?: ServerQuery["page"];
+}
+/**
+ * Validates an untrusted query and maps its operation keys to fields the
+ * backend has approved. Keys are looked up, never interpolated, so an
+ * unlisted key is rejected rather than reaching a query.
+ */
+export declare function resolveServerQuery<TField>(input: unknown, fields: Readonly<Record<string, TField>>): Result<ResolvedQuery<TField>>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,147 @@
+import { ContractError, issuesToDiagnostics, serverQuerySchema, toResult, validateContract } from "@colspec/core";
+//#region src/http.ts
+/** Published revisions never change, so identity plus revision is a strong validator. */
+function etagFor({ tableId, revision }) {
+	return `"${encodeURIComponent(tableId)}@${revision}"`;
+}
+/**
+* Answers a contract retrieval request, including conditional requests, so
+* clients revalidate with a 304 instead of downloading an unchanged contract.
+*/
+async function getDefinitionResponse(service, { tableId, revision, ifNoneMatch }) {
+	const record = await service.getPublished(tableId, revision);
+	if (!record) return {
+		status: 404,
+		headers: {},
+		body: { error: `No published definition for "${tableId}".` }
+	};
+	const etag = etagFor(record);
+	const headers = {
+		ETag: etag,
+		"Cache-Control": "no-cache"
+	};
+	return ifNoneMatch?.split(",").some((candidate) => candidate.trim() === etag) ? {
+		status: 304,
+		headers
+	} : {
+		status: 200,
+		headers,
+		body: record.definition
+	};
+}
+//#endregion
+//#region src/memory-repository.ts
+/** A repository held in memory, for tests, examples and prototypes. */
+function createMemoryRepository() {
+	const records = /* @__PURE__ */ new Map();
+	const keyOf = (tableId, revision) => JSON.stringify([tableId, revision]);
+	const list = (tableId) => [...records.values()].filter((record) => record.tableId === tableId).sort((a, b) => a.revision - b.revision);
+	return {
+		find: async (tableId, revision) => records.get(keyOf(tableId, revision)),
+		findLatest: async (tableId, status) => list(tableId).findLast((record) => record.status === status),
+		list: async (tableId) => list(tableId),
+		save: async (record) => {
+			records.set(keyOf(record.tableId, record.revision), record);
+		}
+	};
+}
+//#endregion
+//#region src/server-query.ts
+/**
+* Validates an untrusted query and maps its operation keys to fields the
+* backend has approved. Keys are looked up, never interpolated, so an
+* unlisted key is rejected rather than reaching a query.
+*/
+function resolveServerQuery(input, fields) {
+	const parsed = serverQuerySchema.safeParse(input);
+	if (!parsed.success) return {
+		ok: false,
+		diagnostics: issuesToDiagnostics(parsed.error.issues, "invalid-query")
+	};
+	const query = parsed.data;
+	const diagnostics = [];
+	const resolve = (entries, section) => (entries ?? []).flatMap(({ key, ...rest }, index) => {
+		if (Object.hasOwn(fields, key)) return [{
+			field: fields[key],
+			...rest
+		}];
+		diagnostics.push({
+			code: "unapproved-key",
+			severity: "error",
+			path: [
+				section,
+				index,
+				"key"
+			],
+			message: `"${key}" is not an approved ${section} key.`
+		});
+		return [];
+	});
+	const resolved = {
+		sort: resolve(query.sort, "sort"),
+		filters: resolve(query.filters, "filters"),
+		page: query.page
+	};
+	return toResult(resolved, diagnostics);
+}
+//#endregion
+//#region src/service.ts
+var DefinitionNotFoundError = class extends Error {
+	constructor(tableId, revision) {
+		super(`No definition found for "${tableId}"${revision ? ` revision ${revision}` : ""}.`);
+		this.name = "DefinitionNotFoundError";
+	}
+};
+var RevisionPublishedError = class extends Error {
+	constructor(tableId, revision) {
+		super(`Revision ${revision} of "${tableId}" is published and can no longer change.`);
+		this.name = "RevisionPublishedError";
+	}
+};
+/** The definition lifecycle on top of any storage implementation. */
+function createTableDefinitionService(repository, { validation, now = () => /* @__PURE__ */ new Date() } = {}) {
+	const validate = (input) => validateContract(input, validation);
+	return {
+		validate,
+		async saveDraft(input) {
+			const result = validate(input);
+			if (!result.ok) throw new ContractError(result.diagnostics);
+			const definition = result.value;
+			const { tableId, revision, schemaVersion } = definition;
+			const existing = await repository.find(tableId, revision);
+			if (existing?.status === "published") throw new RevisionPublishedError(tableId, revision);
+			const timestamp = now();
+			const record = {
+				tableId,
+				revision,
+				schemaVersion,
+				definition,
+				status: "draft",
+				createdAt: existing?.createdAt ?? timestamp,
+				updatedAt: timestamp
+			};
+			await repository.save(record);
+			return record;
+		},
+		async publish(tableId, revision) {
+			const record = await repository.find(tableId, revision);
+			if (!record) throw new DefinitionNotFoundError(tableId, revision);
+			if (record.status === "published") return record;
+			const published = {
+				...record,
+				status: "published",
+				updatedAt: now()
+			};
+			await repository.save(published);
+			return published;
+		},
+		async getPublished(tableId, revision) {
+			if (revision === void 0) return repository.findLatest(tableId, "published");
+			const record = await repository.find(tableId, revision);
+			return record?.status === "published" ? record : void 0;
+		},
+		listRevisions: (tableId) => repository.list(tableId)
+	};
+}
+//#endregion
+export { DefinitionNotFoundError, RevisionPublishedError, createMemoryRepository, createTableDefinitionService, etagFor, getDefinitionResponse, resolveServerQuery };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@colspec/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "devDependencies": {
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "dependencies": {
+    "@colspec/core": "0.1.0"
+  },
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "description": "Store, version, publish and serve colspec table definitions from any database or Node.js framework.",
+  "author": "Om Prakash Das",
+  "homepage": "https://github.com/Om1938/colspec/tree/main/packages/server#readme",
+  "bugs": {
+    "url": "https://github.com/Om1938/colspec/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Om1938/colspec.git",
+    "directory": "packages/server"
+  },
+  "keywords": [
+    "tanstack-table",
+    "tanstack",
+    "table",
+    "datagrid",
+    "dynamic-columns",
+    "colspec",
+    "backend persistence mongodb postgresql"
+  ],
+  "scripts": {
+    "lint": "eslint . --max-warnings 0",
+    "build": "tsdown",
+    "test": "vitest run",
+    "check-types": "tsc --noEmit"
+  }
 }