hbs-magic 0.1.0

package/examples/advanced_csharp-url-helpers/external-input/links.ts

@@ -0,0 +1,182 @@
+import {
+  createRoute,
+  RequiredNumberParam,
+  RequiredStringParam,
+  NumberParam,
+  StringParam,
+  ArrayParam,
+  BooleanParam,
+} from "react-router-url-params";
+
+/**
+ *  This file defines all the routes in some theoretical application using react-router-url-params.
+ *  It is analyzed by preparation-script.ts and produces input-data.json to
+ *  generate C# URL helper methods for ASP.NET Core.
+ */
+
+export const Links = {
+  Unauthorized: {
+    Login: createRoute("/login", undefined, {
+      redirect: StringParam,
+    }),
+
+    Register: createRoute("/register", undefined, {
+      ref: StringParam,
+    }),
+
+    ConfirmEmail: createRoute("/confirm-email/:userId/:token", {
+      userId: RequiredStringParam,
+      token: RequiredStringParam,
+    }),
+
+    ForgotPassword: createRoute("/forgot-password"),
+  },
+
+  Authorized: {
+    Dashboard: createRoute("/", undefined, {
+      tab: StringParam,
+    }),
+
+    Profile: createRoute("/profile/:userId", {
+      userId: RequiredNumberParam,
+      section: StringParam,
+    }),
+
+    Settings: createRoute("/settings", undefined, {
+      page: StringParam,
+    }),
+
+    // ------------------------
+    // Courses
+    // ------------------------
+    Courses: createRoute("/courses", undefined, {
+      page: NumberParam,
+      pageSize: NumberParam,
+      search: StringParam,
+      tags: ArrayParam, // ?tags=a&tags=b
+    }),
+
+    CourseDetails: createRoute("/courses/:courseId", {
+      courseId: RequiredNumberParam,
+      tab: StringParam,
+    }),
+
+    CourseNotFound: createRoute("/courses/:courseId/not-found", {
+      courseId: RequiredNumberParam,
+    }),
+
+    CourseAccessDenied: createRoute("/courses/:courseId/access-denied", {
+      courseId: RequiredNumberParam,
+    }),
+
+    CourseStudents: createRoute("/courses/:courseId/students", {
+      courseId: RequiredNumberParam,
+      page: NumberParam,
+      roles: ArrayParam,
+    }),
+
+    // ------------------------
+    // Assignments
+    // ------------------------
+    AssignmentList: createRoute("/courses/:courseId/assignments", {
+      courseId: RequiredNumberParam,
+      status: StringParam,
+      dueBefore: StringParam,
+    }),
+
+    AssignmentDetails: createRoute(
+      "/courses/:courseId/assignments/:assignmentId",
+      {
+        courseId: RequiredNumberParam,
+        assignmentId: RequiredNumberParam,
+        tab: StringParam,
+      },
+    ),
+
+    AssignmentSubmissions: createRoute(
+      "/courses/:courseId/assignments/:assignmentId/submissions",
+      {
+        courseId: RequiredNumberParam,
+        assignmentId: RequiredNumberParam,
+        page: NumberParam,
+        userIds: ArrayParam,
+      },
+    ),
+
+    // ------------------------
+    // Announcements
+    // ------------------------
+    Announcements: createRoute("/courses/:courseId/announcements", {
+      courseId: RequiredNumberParam,
+      page: NumberParam,
+    }),
+
+    AnnouncementDetails: createRoute(
+      "/courses/:courseId/announcements/:announcementId",
+      {
+        courseId: RequiredNumberParam,
+        announcementId: RequiredNumberParam,
+        highlight: StringParam,
+      },
+    ),
+
+    // ------------------------
+    // Products
+    // ------------------------
+    Products: createRoute("/products", undefined, {
+      page: NumberParam,
+      pageSize: NumberParam,
+      sortBy: StringParam,
+      categories: ArrayParam,
+      minPrice: NumberParam,
+      maxPrice: NumberParam,
+    }),
+
+    ProductDetails: createRoute("/products/:id", {
+      id: RequiredNumberParam,
+    }),
+
+    CreateProduct: createRoute("/products/create", undefined, {
+      templateId: NumberParam,
+    }),
+
+    EditProduct: createRoute("/products/:id/edit", {
+      id: RequiredNumberParam,
+      mode: StringParam,
+    }),
+
+    // ------------------------
+    // Admin
+    // ------------------------
+    Admin: createRoute("/admin", undefined, {
+      tab: StringParam,
+    }),
+
+    AdminUsers: createRoute("/admin/users", undefined, {
+      page: NumberParam,
+      roles: ArrayParam,
+      search: StringParam,
+    }),
+
+    AdminUserDetails: createRoute("/admin/users/:userId", {
+      userId: RequiredNumberParam,
+      tab: StringParam,
+    }),
+
+    // ------------------------
+    // Misc
+    // ------------------------
+    Notifications: createRoute("/notifications", undefined, {
+      unreadOnly: BooleanParam,
+    }),
+
+    Search: createRoute("/search", undefined, {
+      types: ArrayParam,
+      page: NumberParam,
+    }),
+
+    UiKit: createRoute("/uikit", undefined, {
+      component: StringParam,
+    }),
+  },
+};

package/examples/advanced_csharp-url-helpers/input/hbs-helpers.ts

@@ -0,0 +1,93 @@
+/**
+ * Converts TS types into their C# equivalents.
+ */
+function csType(type: string): string {
+  switch (type) {
+    case "string":
+      return "string";
+    case "number":
+      return "int";
+    case "boolean":
+      return "bool";
+    case "array":
+      return "List<string>";
+    case "date":
+      return "DateTime";
+    default:
+      throw new Error(`Unknown type "${type}"`);
+  }
+}
+
+/**
+ * Checks if the node is a group (i.e., has children but no route).
+ * Groups are used for organizational purposes and do not correspond to actual endpoints.
+ */
+function isGroup(node: any) {
+  return !node.route;
+}
+
+/**
+ * Checks if the node is a route (i.e., has a route property).
+ */
+function isRoute(node: any) {
+  return !!node.route;
+}
+
+/**
+ * Converts a field name into its C# property name equivalent by capitalizing the first letter.
+ */
+function csFieldName(name: string) {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/**
+ * Produces a C# expression (depending on type) that checks
+ * whether the value is null or not.
+ */
+function csNullableCheck(fieldName: string, type: string) {
+  const csField = csFieldName(fieldName);
+
+  switch (type) {
+    case "string":
+      return `!string.IsNullOrEmpty(${csField})`;
+    case "number":
+    case "boolean":
+    case "date":
+      return `${csField} != null`;
+    case "array":
+      return `${csField} is { Count: > 0 }`;
+    default:
+      throw new Error(`Unknown type "${type}" for field "${fieldName}"`);
+  }
+}
+
+/**
+ * Produces a C# expression that retrieves
+ * the value to then concatenate it as query parameter.
+ */
+function csNullableValue(fieldName: string, type: string) {
+  const csField = csFieldName(fieldName);
+
+  switch (type) {
+    case "string":
+      return csField;
+    case "boolean":
+    case "number":
+      return `${csField}.Value`;
+    case "array":
+      return `string.Join(",", ${csField})`;
+    case "date":
+      return `${csField}.Value`;
+    default:
+      throw new Error(`Unknown type "${type}" for field "${fieldName}"`);
+  }
+}
+
+export default {
+  isGroup,
+  isRoute,
+  csType,
+  csFieldName,
+  csNullableCheck,
+  csNullableValue,
+};

package/examples/advanced_csharp-url-helpers/input/input-data.json

@@ -0,0 +1,244 @@
+{
+  "Routes": {
+    "Unauthorized": {
+      "Login": {
+        "route": "/login",
+        "queryParams": {
+          "redirect": "string"
+        }
+      },
+      "Register": {
+        "route": "/register",
+        "queryParams": {
+          "ref": "string"
+        }
+      },
+      "ConfirmEmail": {
+        "route": "/confirm-email/:userId/:token",
+        "routeParams": {
+          "userId": "string",
+          "token": "string"
+        }
+      },
+      "ForgotPassword": {
+        "route": "/forgot-password"
+      }
+    },
+    "Authorized": {
+      "Dashboard": {
+        "route": "/",
+        "queryParams": {
+          "tab": "string"
+        }
+      },
+      "Profile": {
+        "route": "/profile/:userId",
+        "routeParams": {
+          "userId": "number",
+          "section": "string"
+        }
+      },
+      "Settings": {
+        "route": "/settings",
+        "queryParams": {
+          "page": "string"
+        }
+      },
+      "Courses": {
+        "route": "/courses",
+        "queryParams": {
+          "page": "number",
+          "pageSize": "number",
+          "search": "string",
+          "tags": "array"
+        }
+      },
+      "CourseDetails": {
+        "route": "/courses/:courseId",
+        "routeParams": {
+          "courseId": "number",
+          "tab": "string"
+        }
+      },
+      "CourseNotFound": {
+        "route": "/courses/:courseId/not-found",
+        "routeParams": {
+          "courseId": "number"
+        }
+      },
+      "CourseAccessDenied": {
+        "route": "/courses/:courseId/access-denied",
+        "routeParams": {
+          "courseId": "number"
+        }
+      },
+      "CourseStudents": {
+        "route": "/courses/:courseId/students",
+        "routeParams": {
+          "courseId": "number",
+          "page": "number",
+          "roles": "array"
+        }
+      },
+      "AssignmentList": {
+        "route": "/courses/:courseId/assignments",
+        "routeParams": {
+          "courseId": "number",
+          "status": "string",
+          "dueBefore": "string"
+        }
+      },
+      "AssignmentDetails": {
+        "route": "/courses/:courseId/assignments/:assignmentId",
+        "routeParams": {
+          "courseId": "number",
+          "assignmentId": "number",
+          "tab": "string"
+        }
+      },
+      "AssignmentSubmissions": {
+        "route": "/courses/:courseId/assignments/:assignmentId/submissions",
+        "routeParams": {
+          "courseId": "number",
+          "assignmentId": "number",
+          "page": "number",
+          "userIds": "array"
+        }
+      },
+      "Announcements": {
+        "route": "/courses/:courseId/announcements",
+        "routeParams": {
+          "courseId": "number",
+          "page": "number"
+        }
+      },
+      "AnnouncementDetails": {
+        "route": "/courses/:courseId/announcements/:announcementId",
+        "routeParams": {
+          "courseId": "number",
+          "announcementId": "number",
+          "highlight": "string"
+        }
+      },
+      "Products": {
+        "route": "/products",
+        "queryParams": {
+          "page": "number",
+          "pageSize": "number",
+          "sortBy": "string",
+          "categories": "array",
+          "minPrice": "number",
+          "maxPrice": "number"
+        }
+      },
+      "ProductDetails": {
+        "route": "/products/:id",
+        "routeParams": {
+          "id": "number"
+        }
+      },
+      "CreateProduct": {
+        "route": "/products/create",
+        "queryParams": {
+          "templateId": "number"
+        }
+      },
+      "EditProduct": {
+        "route": "/products/:id/edit",
+        "routeParams": {
+          "id": "number",
+          "mode": "string"
+        }
+      },
+      "Admin": {
+        "route": "/admin",
+        "queryParams": {
+          "tab": "string"
+        }
+      },
+      "AdminUsers": {
+        "route": "/admin/users",
+        "queryParams": {
+          "page": "number",
+          "roles": "array",
+          "search": "string"
+        }
+      },
+      "AdminUserDetails": {
+        "route": "/admin/users/:userId",
+        "routeParams": {
+          "userId": "number",
+          "tab": "string"
+        }
+      },
+      "Notifications": {
+        "route": "/notifications",
+        "queryParams": {
+          "unreadOnly": "boolean"
+        }
+      },
+      "Search": {
+        "route": "/search",
+        "queryParams": {
+          "types": "array",
+          "page": "number"
+        }
+      },
+      "UiKit": {
+        "route": "/uikit",
+        "queryParams": {
+          "component": "string"
+        }
+      }
+    }
+  },
+  "QueryParamCollections": {
+    "Login": {
+      "redirect": "string"
+    },
+    "Register": {
+      "ref": "string"
+    },
+    "Dashboard": {
+      "tab": "string"
+    },
+    "Settings": {
+      "page": "string"
+    },
+    "Courses": {
+      "page": "number",
+      "pageSize": "number",
+      "search": "string",
+      "tags": "array"
+    },
+    "Products": {
+      "page": "number",
+      "pageSize": "number",
+      "sortBy": "string",
+      "categories": "array",
+      "minPrice": "number",
+      "maxPrice": "number"
+    },
+    "CreateProduct": {
+      "templateId": "number"
+    },
+    "Admin": {
+      "tab": "string"
+    },
+    "AdminUsers": {
+      "page": "number",
+      "roles": "array",
+      "search": "string"
+    },
+    "Notifications": {
+      "unreadOnly": "boolean"
+    },
+    "Search": {
+      "types": "array",
+      "page": "number"
+    },
+    "UiKit": {
+      "component": "string"
+    }
+  }
+}

package/examples/advanced_csharp-url-helpers/input/preparation-script.ts

@@ -0,0 +1,175 @@
+import {
+  Project,
+  SyntaxKind,
+  ObjectLiteralExpression,
+  Node,
+  Symbol,
+} from "ts-morph";
+import ts from "typescript";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const project = new Project({
+  tsConfigFilePath: "tsconfig.json",
+});
+
+const externalInputPath =
+  "examples/advanced_csharp-url-helpers/external-input/links.ts";
+project.addSourceFileAtPath(externalInputPath);
+const sourceFile = project.getSourceFileOrThrow(externalInputPath);
+
+const paramTypeMap: Record<string, string> = {
+  StringParam: "string",
+  RequiredStringParam: "string",
+  NumberParam: "number",
+  RequiredNumberParam: "number",
+  BooleanParam: "boolean",
+  RequiredBooleanParam: "boolean",
+  DateParam: "date",
+  RequiredDateParam: "date",
+  ArrayParam: "array",
+  RequiredArrayParam: "array",
+};
+
+function isFlagPresent(symbol: Symbol, flag: ts.SymbolFlags): boolean {
+  return (symbol.getFlags() & flag) !== 0;
+}
+
+function resolveSpreadObject(node: Node): ObjectLiteralExpression | undefined {
+  let symbol = node.getSymbol();
+  if (!symbol) return;
+
+  if (isFlagPresent(symbol, ts.SymbolFlags.Alias)) {
+    symbol = symbol.getAliasedSymbol();
+  }
+
+  const declarations = symbol?.getDeclarations() ?? [];
+
+  for (const decl of declarations) {
+    if (Node.isVariableDeclaration(decl)) {
+      const init = decl.getInitializer();
+
+      if (Node.isObjectLiteralExpression(init)) {
+        return init;
+      }
+    }
+  }
+
+  return;
+}
+
+function convertParams(obj?: ObjectLiteralExpression) {
+  if (!obj) return undefined;
+
+  const result: Record<string, any> = {};
+
+  for (const prop of obj.getProperties()) {
+    if (Node.isPropertyAssignment(prop)) {
+      const key = prop.getName();
+      const valueText = prop.getInitializer()?.getText() ?? "";
+
+      result[key] = paramTypeMap[valueText] ?? valueText;
+    }
+
+    if (Node.isSpreadAssignment(prop)) {
+      const spreadExpr = prop.getExpression();
+
+      const spreadObj = resolveSpreadObject(spreadExpr);
+
+      if (spreadObj) {
+        const expanded = convertParams(spreadObj);
+        Object.assign(result, expanded);
+      }
+    }
+  }
+
+  return result;
+}
+
+function transformObject(obj: ObjectLiteralExpression): any {
+  const result: Record<string, any> = {};
+
+  for (const prop of obj.getProperties()) {
+    if (!Node.isPropertyAssignment(prop)) continue;
+
+    const key = prop.getName();
+    const initializer = prop.getInitializer();
+
+    if (!initializer) continue;
+
+    if (Node.isCallExpression(initializer)) {
+      if (initializer.getExpression().getText() === "createRoute") {
+        const args = initializer.getArguments();
+
+        const route = args[0]?.getText().replace(/['"]/g, "");
+
+        const routeParams = Node.isObjectLiteralExpression(args[1])
+          ? args[1]
+          : undefined;
+
+        const queryParams = Node.isObjectLiteralExpression(args[2])
+          ? args[2]
+          : undefined;
+
+        result[key] = {
+          route,
+          ...(routeParams ? { routeParams: convertParams(routeParams) } : {}),
+          ...(queryParams ? { queryParams: convertParams(queryParams) } : {}),
+        };
+
+        continue;
+      }
+    }
+
+    if (Node.isObjectLiteralExpression(initializer)) {
+      result[key] = transformObject(initializer);
+    }
+  }
+
+  return result;
+}
+
+function getQueryParamCollections(
+  routesObject: any,
+): Record<string, Record<string, string>> {
+  const collections: Record<string, Record<string, string>> = {};
+
+  function traverse(obj: any) {
+    for (const key in obj) {
+      if (obj[key] && typeof obj[key] === "object") {
+        if (obj[key].queryParams) {
+          collections[key] = obj[key].queryParams;
+        }
+        traverse(obj[key]);
+      }
+    }
+  }
+
+  traverse(routesObject);
+  return collections;
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ *  Example of preparation script that transforms a nested object with route definitions into a JSON `input-data.json`
+ *  for Handlebars template input. It also extracts query parameter collections for easier access in the template.
+ */
+export default function preparationScript() {
+  const rootObject = sourceFile.getFirstDescendantByKindOrThrow(
+    SyntaxKind.ObjectLiteralExpression,
+  );
+
+  const routesObject = transformObject(rootObject);
+  const resultJson = {
+    Routes: routesObject,
+    QueryParamCollections: getQueryParamCollections(routesObject),
+  };
+
+  fs.writeFileSync(
+    path.join(__dirname, "input-data.json"),
+    JSON.stringify(resultJson, null, 2),
+  );
+}