@xrpckit/parser 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+interface ContractDefinition {
+    routers: Router[];
+    types: TypeDefinition[];
+    endpoints: Endpoint[];
+    middleware?: MiddlewareDefinition[];
+}
+interface Router {
+    name: string;
+    endpointGroups: EndpointGroup[];
+    middleware?: MiddlewareDefinition[];
+}
+/**
+ * Middleware definition extracted from router
+ * Middleware functions are stored as metadata and implemented by users in generated code
+ */
+interface MiddlewareDefinition {
+    name?: string;
+}
+interface EndpointGroup {
+    name: string;
+    endpoints: Endpoint[];
+}
+interface Endpoint {
+    name: string;
+    type: 'query' | 'mutation';
+    input: TypeReference;
+    output: TypeReference;
+    fullName: string;
+}
+interface TypeDefinition {
+    name: string;
+    kind: 'object' | 'array' | 'union' | 'primitive' | 'nullable' | 'optional' | 'enum' | 'literal' | 'record' | 'tuple' | 'date';
+    properties?: Property[];
+    elementType?: TypeReference;
+    baseType?: string;
+    unionTypes?: TypeReference[];
+    enumValues?: (string | number)[];
+    literalValue?: string | number | boolean;
+    keyType?: TypeReference;
+    valueType?: TypeReference;
+    tupleElements?: TypeReference[];
+}
+interface ValidationRules {
+    minLength?: number;
+    maxLength?: number;
+    email?: boolean;
+    url?: boolean;
+    uuid?: boolean;
+    regex?: string;
+    min?: number;
+    max?: number;
+    int?: boolean;
+    positive?: boolean;
+    negative?: boolean;
+    minItems?: number;
+    maxItems?: number;
+}
+interface Property {
+    name: string;
+    type: TypeReference;
+    required: boolean;
+    validation?: ValidationRules;
+}
+interface TypeReference {
+    name?: string;
+    kind: TypeDefinition['kind'];
+    baseType?: string | TypeReference;
+    elementType?: TypeReference;
+    properties?: Property[];
+    validation?: ValidationRules;
+    unionTypes?: TypeReference[];
+    enumValues?: (string | number)[];
+    literalValue?: string | number | boolean;
+    keyType?: TypeReference;
+    valueType?: TypeReference;
+    tupleElements?: TypeReference[];
+}
+
+/**
+ * Parses a contract file and returns a normalized contract definition.
+ *
+ * The contract file must export a router created with `createRouter()`.
+ * This function imports the file and extracts type information from Zod schemas.
+ *
+ * @param filePath - Path to the TypeScript file containing the router definition
+ * @returns A promise that resolves to a ContractDefinition containing all routers, endpoints, and types
+ * @throws Error if the file cannot be imported, doesn't export a router, or has invalid structure
+ *
+ * @example
+ * ```typescript
+ * const contract = await parseContract('src/api.ts');
+ * console.log(`Found ${contract.endpoints.length} endpoints`);
+ * ```
+ */
+declare function parseContract(filePath: string): Promise<ContractDefinition>;
+
+export { type ContractDefinition, type Endpoint, type EndpointGroup, type MiddlewareDefinition, type Property, type Router, type TypeDefinition, type TypeReference, type ValidationRules, parseContract };

package/dist/index.js

@@ -0,0 +1,409 @@
+// src/index.ts
+import { resolve } from "path";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+
+// src/zod-extractor.ts
+import { z } from "zod";
+var SAFE_INTEGER_MIN = Number.MIN_SAFE_INTEGER;
+var SAFE_INTEGER_MAX = Number.MAX_SAFE_INTEGER;
+function extractValidationRules(schema) {
+  const rules = {};
+  let hasRules = false;
+  let baseSchema = schema;
+  while (baseSchema instanceof z.ZodOptional || baseSchema instanceof z.ZodNullable) {
+    if (baseSchema instanceof z.ZodOptional) {
+      baseSchema = baseSchema.unwrap();
+    } else if (baseSchema instanceof z.ZodNullable) {
+      baseSchema = baseSchema.unwrap();
+    }
+  }
+  let jsonSchema;
+  try {
+    jsonSchema = baseSchema.toJSONSchema();
+  } catch (e) {
+    return void 0;
+  }
+  if (!jsonSchema || typeof jsonSchema !== "object") {
+    return void 0;
+  }
+  if (baseSchema instanceof z.ZodString) {
+    if (typeof jsonSchema.minLength === "number") {
+      rules.minLength = jsonSchema.minLength;
+      hasRules = true;
+    }
+    if (typeof jsonSchema.maxLength === "number") {
+      rules.maxLength = jsonSchema.maxLength;
+      hasRules = true;
+    }
+    if (jsonSchema.format === "email") {
+      rules.email = true;
+      hasRules = true;
+    }
+    if (jsonSchema.format === "url" || jsonSchema.format === "uri") {
+      rules.url = true;
+      hasRules = true;
+    }
+    if (jsonSchema.format === "uuid") {
+      rules.uuid = true;
+      hasRules = true;
+    }
+    if (jsonSchema.pattern && typeof jsonSchema.pattern === "string") {
+      rules.regex = jsonSchema.pattern;
+      hasRules = true;
+    }
+  } else if (baseSchema instanceof z.ZodNumber) {
+    const isInteger = jsonSchema.type === "integer";
+    if (typeof jsonSchema.minimum === "number") {
+      if (!isInteger || jsonSchema.minimum !== SAFE_INTEGER_MIN) {
+        rules.min = jsonSchema.minimum;
+        hasRules = true;
+      }
+    }
+    if (typeof jsonSchema.maximum === "number") {
+      if (!isInteger || jsonSchema.maximum !== SAFE_INTEGER_MAX) {
+        rules.max = jsonSchema.maximum;
+        hasRules = true;
+      }
+    }
+    if (isInteger) {
+      rules.int = true;
+      hasRules = true;
+    }
+    if (jsonSchema.exclusiveMinimum === 0 || typeof jsonSchema.minimum === "number" && jsonSchema.minimum > 0 && (!isInteger || jsonSchema.minimum !== SAFE_INTEGER_MIN)) {
+      rules.positive = true;
+      hasRules = true;
+    }
+    if (jsonSchema.exclusiveMaximum === 0 || typeof jsonSchema.maximum === "number" && jsonSchema.maximum < 0 && (!isInteger || jsonSchema.maximum !== SAFE_INTEGER_MAX)) {
+      rules.negative = true;
+      hasRules = true;
+    }
+  } else if (baseSchema instanceof z.ZodArray) {
+    if (typeof jsonSchema.minItems === "number") {
+      rules.minItems = jsonSchema.minItems;
+      hasRules = true;
+    }
+    if (typeof jsonSchema.maxItems === "number") {
+      rules.maxItems = jsonSchema.maxItems;
+      hasRules = true;
+    }
+  }
+  return hasRules ? rules : void 0;
+}
+function extractTypeInfo(schema) {
+  if (schema instanceof z.ZodOptional) {
+    const unwrapped = schema.unwrap();
+    return {
+      kind: "optional",
+      baseType: extractTypeInfo(unwrapped)
+    };
+  }
+  if (schema instanceof z.ZodNullable) {
+    const unwrapped = schema.unwrap();
+    return {
+      kind: "nullable",
+      baseType: extractTypeInfo(unwrapped)
+    };
+  }
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+    const properties = [];
+    for (const [key, value] of Object.entries(shape)) {
+      const valueType = extractTypeInfo(value);
+      const isOptional = value instanceof z.ZodOptional;
+      const validation = extractValidationRules(value);
+      properties.push({
+        name: key,
+        type: valueType,
+        required: !isOptional,
+        validation
+      });
+    }
+    return {
+      kind: "object",
+      properties
+    };
+  }
+  if (schema instanceof z.ZodArray) {
+    const elementType = extractTypeInfo(schema.element);
+    const validation = extractValidationRules(schema);
+    return {
+      kind: "array",
+      elementType,
+      validation
+    };
+  }
+  if (schema instanceof z.ZodString) {
+    return {
+      kind: "primitive",
+      baseType: "string"
+    };
+  }
+  if (schema instanceof z.ZodNumber) {
+    return {
+      kind: "primitive",
+      baseType: "number"
+    };
+  }
+  if (schema instanceof z.ZodBoolean) {
+    return {
+      kind: "primitive",
+      baseType: "boolean"
+    };
+  }
+  if (schema instanceof z.ZodUnion) {
+    const options = schema.options;
+    return {
+      kind: "union",
+      unionTypes: options.map((opt) => extractTypeInfo(opt))
+    };
+  }
+  if (schema instanceof z.ZodEnum) {
+    return {
+      kind: "enum",
+      enumValues: schema.options
+    };
+  }
+  if (schema instanceof z.ZodLiteral) {
+    return {
+      kind: "literal",
+      literalValue: schema.value,
+      baseType: typeof schema.value
+    };
+  }
+  if (schema instanceof z.ZodRecord) {
+    return {
+      kind: "record",
+      keyType: { kind: "primitive", baseType: "string" },
+      valueType: extractTypeInfo(schema.valueSchema)
+    };
+  }
+  if (schema instanceof z.ZodTuple) {
+    return {
+      kind: "tuple",
+      tupleElements: schema.items.map((item) => extractTypeInfo(item))
+    };
+  }
+  if (schema instanceof z.ZodDate) {
+    return {
+      kind: "date",
+      baseType: "date"
+    };
+  }
+  return {
+    kind: "primitive",
+    baseType: "unknown"
+  };
+}
+function generateTypeName(prefix, suffix) {
+  const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+  return capitalize(prefix) + capitalize(suffix);
+}
+
+// src/index.ts
+import { getRouterMiddleware } from "@xrpckit/schema";
+async function importWithTimeout(path, timeout = 5e3) {
+  const timeoutPromise = new Promise(
+    (_, reject) => setTimeout(() => reject(new Error(`Import timeout after ${timeout}ms`)), timeout)
+  );
+  return Promise.race([import(path), timeoutPromise]);
+}
+async function parseContract(filePath) {
+  const absolutePath = resolve(filePath);
+  let routerModule;
+  try {
+    routerModule = await importWithTimeout(absolutePath);
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message.includes("timeout")) {
+        throw new Error(
+          `Contract file import timed out: ${filePath}
+This may indicate circular dependencies or slow initialization.
+Ensure the file exports a router synchronously.`
+        );
+      }
+      if (error.message.includes("Cannot find module")) {
+        throw new Error(
+          `Failed to import contract file: ${filePath}
+Error: ${error.message}
+Make sure the file exists and all dependencies are installed.`
+        );
+      }
+      if (error.message.includes("Unexpected token") || error.message.includes("SyntaxError")) {
+        throw new Error(
+          `Syntax error in contract file: ${filePath}
+Error: ${error.message}
+Please check the file for syntax errors.`
+        );
+      }
+      throw new Error(
+        `Failed to parse contract file: ${filePath}
+Error: ${error.message}`
+      );
+    }
+    throw error;
+  }
+  if (!routerModule.router) {
+    if ("router" in routerModule) {
+      throw new Error(
+        `Invalid router export in ${filePath}.
+The router export exists but is not a valid RouterDefinition.
+Make sure you're using: export const router = createRouter({ ... });`
+      );
+    }
+    const exports = Object.keys(routerModule);
+    if (exports.length === 0) {
+      throw new Error(
+        `No exports found in ${filePath}.
+The contract file must export a router. Example:
+  export const router = createRouter({ ... });`
+      );
+    }
+    const possibleExports = exports.filter((e) => e.toLowerCase().includes("router"));
+    if (possibleExports.length > 0) {
+      throw new Error(
+        `No router export found in ${filePath}.
+Found exports: ${exports.join(", ")}
+Did you mean to export one of these? Make sure to use: export const router = createRouter({ ... });`
+      );
+    }
+    throw new Error(
+      `No router export found in ${filePath}.
+The contract file must export a router. Example:
+  export const router = createRouter({ ... });
+Found exports: ${exports.length > 0 ? exports.join(", ") : "none"}`
+    );
+  }
+  const routerDef = routerModule.router;
+  try {
+    return buildContractDefinition(routerDef);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(
+        `Failed to build contract from router definition: ${error.message}
+File: ${filePath}`
+      );
+    }
+    throw error;
+  }
+}
+function buildContractDefinition(routerDef) {
+  const routers = [];
+  const endpoints = [];
+  const typeMap = /* @__PURE__ */ new Map();
+  if (!routerDef || typeof routerDef !== "object") {
+    throw new Error("Router definition must be an object. Use: createRouter({ ... })");
+  }
+  const middleware = getRouterMiddleware(routerDef);
+  const middlewareDefinitions = middleware?.map((_, index) => ({
+    name: `middleware_${index}`
+  })) || [];
+  const router = {
+    name: "router",
+    endpointGroups: [],
+    middleware: middlewareDefinitions.length > 0 ? middlewareDefinitions : void 0
+  };
+  for (const [groupName, groupDef] of Object.entries(routerDef)) {
+    if (!groupDef || typeof groupDef !== "object") {
+      throw new Error(
+        `Invalid endpoint group "${groupName}". Endpoint groups must be created with createEndpoint({ ... }).`
+      );
+    }
+    const endpointGroup = {
+      name: groupName,
+      endpoints: []
+    };
+    for (const [endpointName, endpointDef] of Object.entries(groupDef)) {
+      const fullName = `${groupName}.${endpointName}`;
+      const epDef = endpointDef;
+      if (!epDef || typeof epDef !== "object") {
+        throw new Error(
+          `Invalid endpoint "${fullName}". Endpoints must be created with query({ ... }) or mutation({ ... }).`
+        );
+      }
+      if (!epDef.type || epDef.type !== "query" && epDef.type !== "mutation") {
+        throw new Error(
+          `Invalid endpoint type for "${fullName}". Type must be "query" or "mutation", got: ${epDef.type}`
+        );
+      }
+      if (!epDef.input) {
+        throw new Error(
+          `Endpoint "${fullName}" is missing input schema. Use: ${epDef.type}({ input: z.object({ ... }), output: z.object({ ... }) })`
+        );
+      }
+      if (!epDef.output) {
+        throw new Error(
+          `Endpoint "${fullName}" is missing output schema. Use: ${epDef.type}({ input: z.object({ ... }), output: z.object({ ... }) })`
+        );
+      }
+      try {
+        const inputType = extractTypeInfo(epDef.input);
+        const inputTypeName = generateTypeName(groupName, endpointName) + "Input";
+        addTypeDefinition(typeMap, inputTypeName, inputType);
+        const outputType = extractTypeInfo(epDef.output);
+        const outputTypeName = generateTypeName(groupName, endpointName) + "Output";
+        addTypeDefinition(typeMap, outputTypeName, outputType);
+        const endpoint = {
+          name: endpointName,
+          type: epDef.type,
+          input: { name: inputTypeName, ...inputType },
+          output: { name: outputTypeName, ...outputType },
+          fullName
+        };
+        endpointGroup.endpoints.push(endpoint);
+        endpoints.push(endpoint);
+      } catch (error) {
+        if (error instanceof Error) {
+          throw new Error(
+            `Failed to extract type information for endpoint "${fullName}": ${error.message}`
+          );
+        }
+        throw error;
+      }
+    }
+    if (endpointGroup.endpoints.length === 0) {
+      throw new Error(
+        `Endpoint group "${groupName}" has no endpoints. Add endpoints using: createEndpoint({ endpointName: query({ ... }) })`
+      );
+    }
+    router.endpointGroups.push(endpointGroup);
+  }
+  if (router.endpointGroups.length === 0) {
+    throw new Error(
+      "Router has no endpoint groups. Add endpoint groups using: createRouter({ groupName: createEndpoint({ ... }) })"
+    );
+  }
+  routers.push(router);
+  return {
+    routers,
+    types: Array.from(typeMap.values()),
+    endpoints,
+    middleware: middlewareDefinitions.length > 0 ? middlewareDefinitions : void 0
+  };
+}
+function addTypeDefinition(typeMap, name, typeRef) {
+  if (typeMap.has(name)) {
+    return;
+  }
+  const typeDef = {
+    name,
+    kind: typeRef.kind,
+    properties: typeRef.properties,
+    elementType: typeRef.elementType,
+    baseType: typeRef.baseType
+  };
+  typeMap.set(name, typeDef);
+  if (typeRef.properties) {
+    for (const prop of typeRef.properties) {
+      if (prop.type.name && !typeMap.has(prop.type.name)) {
+        addTypeDefinition(typeMap, prop.type.name, prop.type);
+      }
+    }
+  }
+  if (typeRef.elementType && typeRef.elementType.name && !typeMap.has(typeRef.elementType.name)) {
+    addTypeDefinition(typeMap, typeRef.elementType.name, typeRef.elementType);
+  }
+}
+export {
+  parseContract
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xrpckit/parser",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mwesox/xrpc.git",
+    "directory": "packages/parser"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@xrpckit/schema": "^0.0.1",
+    "typescript": "^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}