@kosmojs/lib 0.0.26

package/pkg/index.js

@@ -0,0 +1,1346 @@
+// src/ast.ts
+import { resolve } from "node:path";
+import { styleText } from "node:util";
+import crc from "crc/crc32";
+import { flattener } from "tfusion";
+import {
+  Project,
+  SyntaxKind
+} from "ts-morph";
+import {
+  HTTPMethods,
+  RequestValidationTargets
+} from "@kosmojs/api";
+var astFactory = () => {
+  const createProject = (opts) => new Project(opts);
+  const resolveRouteSignature = async (route, opts) => {
+    const {
+      sourceFile = createProject().addSourceFileAtPath(route.fileFullpath)
+    } = { ...opts };
+    const [typeDeclarations, referencedFiles] = extractTypeDeclarations(
+      sourceFile,
+      opts
+    );
+    const defaultExport = extractDefaultExport(sourceFile);
+    const paramsRefinements = defaultExport ? extractParamsRefinements(defaultExport) : void 0;
+    const methods = defaultExport ? extractRouteMethods(route, defaultExport) : [];
+    return {
+      typeDeclarations,
+      paramsRefinements,
+      methods: methods.map((e) => e.method),
+      validationDefinitions: methods.flatMap((e) => e.validationDefinitions),
+      referencedFiles
+    };
+  };
+  const extractDefaultExport = (sourceFile) => {
+    const [defaultExport] = sourceFile.getExportAssignments().flatMap((exportAssignment) => {
+      if (exportAssignment.isExportEquals()) {
+        return [];
+      }
+      const callExpression = exportAssignment.getExpression();
+      return callExpression.isKind(SyntaxKind.CallExpression) ? [callExpression] : [];
+    });
+    return defaultExport;
+  };
+  const extractParamsRefinements = (callExpression) => {
+    const [
+      _routeName,
+      // first generic - the route name
+      paramsGeneric
+      // second generic - params refinements
+    ] = extractGenerics(callExpression);
+    if (!paramsGeneric?.isKind(SyntaxKind.TupleType)) {
+      return;
+    }
+    return paramsGeneric.getElements().map((node, index) => {
+      return {
+        index,
+        text: node.getText()
+      };
+    });
+  };
+  const extractRouteMethods = (route, callExpression) => {
+    const funcDeclaration = callExpression.getFirstChildByKind(SyntaxKind.ArrowFunction) || callExpression.getFirstChildByKind(SyntaxKind.FunctionExpression);
+    if (!funcDeclaration) {
+      return [];
+    }
+    const arrayLiteralExpression = funcDeclaration.getFirstChildByKind(
+      SyntaxKind.ArrayLiteralExpression
+    );
+    if (!arrayLiteralExpression) {
+      return [];
+    }
+    const callExpressions = [];
+    for (const e of arrayLiteralExpression.getChildrenOfKind(
+      SyntaxKind.CallExpression
+    )) {
+      const name = e.getExpression().getText();
+      if (HTTPMethods[name]) {
+        callExpressions.push([e, name]);
+      }
+    }
+    const methods = [];
+    for (const [callExpression2, method] of callExpressions) {
+      const [vDefs, vOpts] = extractGenerics(callExpression2);
+      methods.push({
+        method,
+        validationDefinitions: extractValidationDefinitions(
+          route,
+          method,
+          vDefs,
+          vOpts
+        )
+      });
+    }
+    return methods;
+  };
+  const parseRuntimeValidation = (typeNode) => {
+    if (typeNode.isKind(SyntaxKind.LiteralType)) {
+      const literal = typeNode.getFirstChild();
+      if (literal?.isKind(SyntaxKind.TrueKeyword)) {
+        return true;
+      } else if (literal?.isKind(SyntaxKind.FalseKeyword)) {
+        return false;
+      }
+    }
+    return void 0;
+  };
+  const extractResponseVariant = (typeNode) => {
+    if (!typeNode.isKind(SyntaxKind.TupleType)) {
+      return;
+    }
+    let status = 200;
+    let contentType;
+    let body;
+    const [statusNode, contentTypeNode, bodyNode] = typeNode.getElements();
+    if (statusNode?.isKind(SyntaxKind.LiteralType)) {
+      const literal = statusNode.getFirstChildByKind(SyntaxKind.NumericLiteral);
+      if (literal) {
+        status = Number(literal.getText());
+      }
+    }
+    if (contentTypeNode) {
+      contentType = extractStringLiteral(contentTypeNode);
+    }
+    if (bodyNode) {
+      body = bodyNode.getText();
+      if (["object"].includes(body)) {
+        body = "{}";
+      }
+    }
+    return { status, contentType, body };
+  };
+  const parseValidationOptions = (typeNode) => {
+    const opts = {};
+    if (!typeNode?.isKind(SyntaxKind.TypeLiteral)) {
+      return opts;
+    }
+    for (const prop of typeNode.getMembers()) {
+      if (!prop.isKind(SyntaxKind.PropertySignature)) {
+        continue;
+      }
+      const target = prop.getName();
+      const typeNode2 = prop.getTypeNodeOrThrow();
+      if (!typeNode2.isKind(SyntaxKind.TypeLiteral)) {
+        continue;
+      }
+      let contentType;
+      let runtimeValidation;
+      const customErrors = {};
+      for (const member of typeNode2.getMembers()) {
+        if (!member.isKind(SyntaxKind.PropertySignature)) {
+          continue;
+        }
+        const nameNode = member.getNameNode();
+        const valueNode = member.getTypeNodeOrThrow();
+        const name = nameNode.isKind(SyntaxKind.StringLiteral) ? nameNode.getLiteralText() : nameNode.getText();
+        if (name === "contentType") {
+          contentType = extractStringLiteral(valueNode);
+        } else if (name === "runtimeValidation") {
+          runtimeValidation = parseRuntimeValidation(valueNode);
+        } else if (name.startsWith("error")) {
+          const literal = extractStringLiteral(valueNode);
+          if (literal) {
+            customErrors[name] = literal;
+          }
+        }
+      }
+      opts[target] = {
+        contentType,
+        runtimeValidation,
+        customErrors
+      };
+    }
+    return opts;
+  };
+  const extractStringLiteral = (typeNode) => {
+    const literal = typeNode.isKind(SyntaxKind.LiteralType) ? typeNode.getFirstChildByKind(SyntaxKind.StringLiteral) : void 0;
+    return literal ? literal.getLiteralText() : void 0;
+  };
+  const extractValidationDefinitions = (route, method, defsNode, optsNode) => {
+    const definitions = [];
+    if (!defsNode?.isKind(SyntaxKind.TypeLiteral)) {
+      return definitions;
+    }
+    const optsMap = parseValidationOptions(optsNode);
+    const createId = (target, hash) => {
+      return [
+        target.replace(/^./, (c) => c.toUpperCase()),
+        "T",
+        method,
+        crc(route.id + hash)
+      ].join("");
+    };
+    for (const prop of defsNode.getMembers()) {
+      if (!prop.isKind(SyntaxKind.PropertySignature)) {
+        continue;
+      }
+      const target = prop.getName();
+      const typeNode = prop.getTypeNodeOrThrow();
+      if (target === "response") {
+        const variants = typeNode.isKind(SyntaxKind.UnionType) ? typeNode.getChildrenOfKind(SyntaxKind.TupleType) : [typeNode];
+        definitions.push({
+          ...optsMap[target],
+          method,
+          target,
+          variants: variants.flatMap((e, i) => {
+            const { status, contentType, body } = extractResponseVariant(e) || {};
+            if (!status) {
+              return [];
+            }
+            if (contentType && typeof contentType !== "string") {
+              console.warn(
+                styleText(
+                  ["bold", "red"],
+                  `\u2717 The second element of a response variant should specify the Response Content Type`
+                )
+              );
+              console.warn(
+                styleText(["blue"], `  Example: [200, "json", Schema]`)
+              );
+              console.warn(
+                `  Route: ${route.name}; Method: ${method}; Response Variant: #${i}`
+              );
+              console.warn();
+            }
+            return [
+              {
+                id: createId(
+                  target,
+                  JSON.stringify([status, contentType, body])
+                ),
+                status,
+                contentType,
+                body
+              }
+            ];
+          })
+        });
+      } else if (Object.keys(RequestValidationTargets).includes(target)) {
+        definitions.push({
+          ...optsMap[target],
+          method,
+          target,
+          schema: {
+            id: createId(target),
+            text: typeNode.getText()
+          }
+        });
+      }
+    }
+    return definitions;
+  };
+  const extractTypeDeclarations = (sourceFile, opts) => {
+    const declarations = [];
+    const referencedFiles = opts?.withReferencedFiles ? [] : void 0;
+    for (const declaration of sourceFile.getImportDeclarations()) {
+      const modulePath = declaration.getModuleSpecifierValue();
+      const path = /^\.\.?\/?/.test(modulePath) ? opts?.relpathResolver ? opts.relpathResolver(modulePath) : modulePath : modulePath;
+      const typeOnlyDeclaration = declaration.isTypeOnly();
+      const defaultImport = typeOnlyDeclaration ? declaration.getDefaultImport() : void 0;
+      if (defaultImport) {
+        const name = defaultImport.getText();
+        const text = `import type ${name} from "${path}";`;
+        declarations.push({
+          importDeclaration: {
+            name,
+            path
+          },
+          text
+        });
+        if (referencedFiles) {
+          referencedFiles.push(...getReferencedFiles(defaultImport));
+        }
+      }
+      for (const namedImport of declaration.getNamedImports()) {
+        if (namedImport.isTypeOnly() || typeOnlyDeclaration) {
+          const nameNode = namedImport.getNameNode();
+          const name = nameNode.getText();
+          const alias = namedImport.getAliasNode()?.getText();
+          const nameText = alias ? `${name} as ${alias}` : name;
+          declarations.push({
+            importDeclaration: {
+              name,
+              alias,
+              path
+            },
+            text: `import type { ${nameText} } from "${path}";`
+          });
+          if (referencedFiles) {
+            if (nameNode.isKind(SyntaxKind.Identifier)) {
+              referencedFiles.push(...getReferencedFiles(nameNode));
+            }
+          }
+        }
+      }
+    }
+    for (const declaration of sourceFile.getTypeAliases()) {
+      const name = declaration.getName();
+      const text = declaration.getFullText().trim();
+      declarations.push({
+        typeAliasDeclaration: { name },
+        text
+      });
+    }
+    for (const declaration of sourceFile.getInterfaces()) {
+      const name = declaration.getName();
+      const text = declaration.getFullText().trim();
+      declarations.push({
+        interfaceDeclaration: { name },
+        text
+      });
+    }
+    for (const declaration of sourceFile.getEnums()) {
+      const name = declaration.getName();
+      const text = declaration.getFullText().trim();
+      declarations.push({
+        enumDeclaration: { name },
+        text
+      });
+    }
+    for (const declaration of sourceFile.getExportDeclarations()) {
+      const typeOnlyDeclaration = declaration.isTypeOnly();
+      const modulePath = declaration.getModuleSpecifierValue();
+      const path = modulePath ? /^\.\.?\/?/.test(modulePath) ? opts?.relpathResolver ? opts.relpathResolver(modulePath) : modulePath : modulePath : void 0;
+      for (const namedExport of declaration.getNamedExports()) {
+        if (namedExport.isTypeOnly() || typeOnlyDeclaration) {
+          const nameNode = namedExport.getNameNode();
+          const name = nameNode.getText();
+          const alias = namedExport.getAliasNode()?.getText();
+          const nameText = alias ? `${name} as ${alias}` : name;
+          declarations.push({
+            exportDeclaration: {
+              name,
+              alias: alias ?? name,
+              path
+            },
+            text: path ? `export type { ${nameText} } from "${path}";` : `export type { ${nameText} };`
+          });
+          if (referencedFiles) {
+            if (nameNode.isKind(SyntaxKind.Identifier)) {
+              referencedFiles.push(...getReferencedFiles(nameNode));
+            }
+          }
+        }
+      }
+    }
+    return referencedFiles ? [declarations, [...new Set(referencedFiles)]] : [declarations];
+  };
+  const getReferencedFiles = (importIdentifier) => {
+    const declarations = importIdentifier?.getSymbol()?.getAliasedSymbol()?.getDeclarations() || [];
+    return declarations.flatMap((e) => {
+      const sourceFile = e.getSourceFile();
+      return sourceFile ? [sourceFile.getFilePath()] : [];
+    });
+  };
+  const extractGenerics = (callExpression) => {
+    return callExpression.getTypeArguments();
+  };
+  const typeResolverFactory = ({ root }) => {
+    const project = createProject({
+      tsConfigFilePath: resolve(root, "tsconfig.json"),
+      skipAddingFilesFromTsConfig: true
+    });
+    const literalTypesResolver = (literalTypes, options) => {
+      const sourceFile = project.createSourceFile(
+        `${crc(literalTypes)}-${Date.now()}.ts`,
+        literalTypes,
+        { overwrite: true }
+      );
+      const resolvedTypes = flattener(project, sourceFile, {
+        ...options,
+        stripComments: true
+      });
+      project.removeSourceFile(sourceFile);
+      return resolvedTypes;
+    };
+    return {
+      getSourceFile: (fileFullpath) => {
+        return project.getSourceFile(fileFullpath) || project.addSourceFileAtPath(fileFullpath);
+      },
+      refreshSourceFile: async (fileFullpath) => {
+        const sourceFile = project.getSourceFile(fileFullpath);
+        if (sourceFile) {
+          await sourceFile.refreshFromFileSystem();
+        }
+      },
+      literalTypesResolver
+    };
+  };
+  return {
+    createProject,
+    extractDefaultExport,
+    extractParamsRefinements,
+    extractRouteMethods,
+    extractTypeDeclarations,
+    resolveRouteSignature,
+    typeResolverFactory
+  };
+};
+
+// src/defaults.ts
+var defaults = {
+  appPrefix: "~",
+  srcPrefix: "@",
+  libPrefix: "_",
+  coreDir: "core",
+  srcDir: "src",
+  libDir: "lib",
+  configDir: "config",
+  apiDir: "api",
+  pagesDir: "pages",
+  entryDir: "entry",
+  fetchDir: "fetch",
+  refineTypeName: "VRefine"
+};
+
+// src/generators.ts
+var GENERATOR_META = /* @__PURE__ */ Symbol.for("KOSMO:GENERATOR_META");
+var defineGenerator = (factory, meta) => {
+  const value = meta ? deepFreeze(structuredClone(meta)) : void 0;
+  const defineProperty = (fn) => {
+    Object.defineProperty(fn, GENERATOR_META, {
+      value,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+    return fn;
+  };
+  return defineProperty((...args) => {
+    return defineProperty(factory(...args));
+  });
+};
+var isGenerator = (fn) => {
+  return GENERATOR_META in fn;
+};
+var getGeneratorMeta = (fn) => {
+  return fn[GENERATOR_META];
+};
+var defineGeneratorFactory = (f) => f;
+var deepFreeze = (obj) => {
+  if (obj && typeof obj === "object" && !Object.isFrozen(obj)) {
+    Object.freeze(obj);
+    for (const prop of Object.getOwnPropertyNames(obj)) {
+      deepFreeze(obj[prop]);
+    }
+  }
+  return obj;
+};
+
+// src/paths.ts
+import { access, constants } from "node:fs/promises";
+import { join, resolve as resolve2 } from "node:path";
+var createTsconfigPaths = (prefix) => {
+  return {
+    [`${defaults.appPrefix}/*`]: [`${prefix}/*`],
+    [`${defaults.srcPrefix}/*`]: [`${prefix}/${defaults.srcDir}/*`],
+    [`${defaults.libPrefix}/*`]: [
+      `${prefix}/${defaults.libDir}/${defaults.srcDir}/*`
+    ]
+  };
+};
+var pathResolver = (sourceFolder) => {
+  const createPath = (...a) => {
+    return sourceFolder.root ? resolve2(sourceFolder.root, join(...a)) : join(...a);
+  };
+  const createImport = {
+    src(...a) {
+      return join(defaults.srcPrefix, sourceFolder.name, ...a);
+    },
+    config(...a) {
+      return this.src(defaults.configDir, ...a);
+    },
+    api(...a) {
+      return this.src(defaults.apiDir, ...a);
+    },
+    pages(...a) {
+      return this.src(defaults.pagesDir, ...a);
+    },
+    lib(...a) {
+      return join(defaults.libPrefix, sourceFolder.name, ...a);
+    },
+    libApi(...a) {
+      return this.lib(defaults.apiDir, ...a);
+    },
+    libEntry(...a) {
+      return this.lib(defaults.entryDir, ...a);
+    }
+  };
+  return {
+    createPath: {
+      src(...a) {
+        return createPath(defaults.srcDir, sourceFolder.name, ...a);
+      },
+      api(...a) {
+        return this.src(defaults.apiDir, ...a);
+      },
+      pages(...a) {
+        return this.src(defaults.pagesDir, ...a);
+      },
+      config(...a) {
+        return this.src(defaults.configDir, ...a);
+      },
+      entry(...a) {
+        return this.src(defaults.entryDir, ...a);
+      },
+      lib(...a) {
+        return createPath(
+          defaults.libDir,
+          defaults.srcDir,
+          sourceFolder.name,
+          ...a
+        );
+      },
+      libApi(...a) {
+        return this.lib(defaults.apiDir, ...a);
+      },
+      libEntry(...a) {
+        return this.lib(defaults.entryDir, ...a);
+      },
+      libPages(...a) {
+        return this.lib(defaults.pagesDir, ...a);
+      },
+      distDir(...a) {
+        return createPath(sourceFolder.distDir, sourceFolder.name, ...a);
+      }
+    },
+    createImport,
+    createImportHelper: (key, ...a) => {
+      return createImport[key](...a.slice(0, -1));
+    }
+  };
+};
+var pathExists = async (path) => {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// src/render.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join as join2 } from "node:path";
+import crc2 from "crc/crc32";
+import handlebars from "handlebars";
+var render = (template, context, options) => {
+  const { noEscape = true, renderer = handlebars } = { ...options };
+  return renderer.compile(template, { noEscape })(context);
+};
+var renderToFile = async (file, template, context, options) => {
+  const content = render(template, context, options);
+  if (await pathExists(file)) {
+    const { overwrite = true } = { ...options };
+    if (overwrite === false) {
+      return;
+    }
+    const fileContent = await readFile(file, "utf8");
+    if (typeof overwrite === "function" && !overwrite(fileContent)) {
+      return;
+    }
+    if (crc2(content) === crc2(fileContent)) {
+      return;
+    }
+  }
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, content, "utf8");
+};
+var renderFactory = (options) => {
+  const renderer = handlebars.create();
+  renderer.registerPartial({ ...options?.partials });
+  renderer.registerHelper({ ...options?.helpers });
+  return {
+    render(template, context, selfOoptions) {
+      return render(template, context, {
+        renderer,
+        ...options,
+        ...selfOoptions
+      });
+    },
+    async renderToFile(file, template, context, selfOoptions) {
+      return renderToFile(
+        options?.outdir ? join2(options.outdir, file) : file,
+        template,
+        context,
+        { renderer, ...options, ...selfOoptions }
+      );
+    }
+  };
+};
+var renderHelpers = {
+  createParamsLiteral: (params) => {
+    return params.schema.map((p) => {
+      return p.kind === "splat" ? `${p.const}?: Array<string | number>` : p.kind === "optional" ? `${p.const}?: string | number` : `${p.const}: string | number`;
+    }).join(", ");
+  }
+};
+
+// src/routes/base.ts
+import { dirname as dirname2, join as join3, resolve as resolve3 } from "node:path";
+import { styleText as styleText2 } from "node:util";
+import crc3 from "crc/crc32";
+import { parse } from "path-to-regexp";
+import picomatch from "picomatch";
+import { glob } from "tinyglobby";
+var API_INDEX_BASENAME = "index";
+var API_INDEX_PATTERN = `${API_INDEX_BASENAME}.ts`;
+var API_USE_BASENAME = "use";
+var API_USE_PATTERN = `${API_USE_BASENAME}.ts`;
+var PAGE_INDEX_BASENAME = "index";
+var PAGE_INDEX_PATTERN = `${PAGE_INDEX_BASENAME}.{tsx,vue}`;
+var PAGE_LAYOUT_BASENAME = "layout";
+var PAGE_LAYOUT_PATTERN = `${PAGE_LAYOUT_BASENAME}.{tsx,vue}`;
+var ROUTE_FILE_PATTERNS = [
+  // match index files in api dir
+  `${defaults.apiDir}/**/${API_INDEX_PATTERN}`,
+  // match use files in api dir
+  `${defaults.apiDir}/**/${API_USE_PATTERN}`,
+  // match index files in pages dir
+  `${defaults.pagesDir}/**/${PAGE_INDEX_PATTERN}`,
+  // match layout files in pages dir
+  `${defaults.pagesDir}/**/${PAGE_LAYOUT_PATTERN}`
+];
+var scanRoutes = async (sourceFolder) => {
+  const { createPath } = pathResolver(sourceFolder);
+  return glob(ROUTE_FILE_PATTERNS, {
+    cwd: createPath.src(),
+    absolute: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    ignore: [
+      // ignore top-level matches, routes resides in folders, even index route
+      `${defaults.apiDir}/${API_INDEX_PATTERN}`,
+      `${defaults.apiDir}/${API_USE_PATTERN}`,
+      `${defaults.pagesDir}/${PAGE_INDEX_PATTERN}`,
+      `${defaults.pagesDir}/${PAGE_LAYOUT_PATTERN}`
+    ]
+  });
+};
+var isRouteFile = (file, sourceFolder) => {
+  const [_sourceFolder, _folder, ...rest] = resolve3(sourceFolder.root, file).replace(`${sourceFolder.root}/${defaults.srcDir}/`, "").split("/");
+  if (!_folder || _sourceFolder !== sourceFolder.name || rest.length < 2) {
+    return false;
+  }
+  return picomatch.isMatch(join3(_folder, ...rest), ROUTE_FILE_PATTERNS) ? [_folder, rest.join("/")] : false;
+};
+var isApiRoute = (file) => {
+  return picomatch.matchBase(file, `**/${API_INDEX_PATTERN}`);
+};
+var isApiUse = (file) => {
+  return picomatch.matchBase(file, `**/${API_USE_PATTERN}`);
+};
+var isPageRoute = (file) => {
+  return picomatch.matchBase(file, `**/${PAGE_INDEX_PATTERN}`);
+};
+var isPageLayout = (file) => {
+  return picomatch.matchBase(file, `**/${PAGE_LAYOUT_PATTERN}`);
+};
+var createRouteEntry = (fileFullpath, sourceFolder) => {
+  const resolvedPaths = isRouteFile(fileFullpath, sourceFolder);
+  if (!resolvedPaths) {
+    return;
+  }
+  const [folder, file] = resolvedPaths;
+  const id = `${file.replace(/\W+/g, "_")}_${crc3(file)}`;
+  const name = dirname2(file);
+  try {
+    const [pathTokens, pathPattern] = pathTokensFactory(dirname2(file));
+    return { id, name, folder, file, fileFullpath, pathTokens, pathPattern };
+  } catch (error) {
+    console.error(
+      `\u2757${styleText2("red", "ERROR")}: Failed parsing path for "${styleText2("cyan", file)}"`
+    );
+    console.error(error);
+    return;
+  }
+};
+var pathTokensFactory = (path, {
+  transformStaticValue = normalizeStaticValue
+} = {}) => {
+  const extractParts = (tokens2, createConst, insideGroup = false) => {
+    const parts = [];
+    for (const token of tokens2) {
+      switch (token.type) {
+        case "text":
+          if (token.value !== "/") {
+            parts.push({
+              type: "static",
+              value: transformStaticValue(token.value)
+            });
+          }
+          break;
+        case "param":
+          parts.push({
+            type: "param",
+            kind: insideGroup ? "optional" : "required",
+            name: token.name,
+            const: createConst(token.name)
+          });
+          break;
+        case "wildcard":
+          parts.push({
+            type: "param",
+            kind: "splat",
+            name: token.name,
+            const: createConst(token.name)
+          });
+          break;
+        case "group":
+          parts.push(...extractParts(token.tokens, createConst, true));
+          break;
+      }
+    }
+    return parts;
+  };
+  const patternTransforms = [
+    // Transform required params: [id] => :id
+    // Only pure \w param names,
+    // [some-id] used as is, not treated as param,
+    // use [some_id] instead.
+    (s) => s.replace(/\[(\w+)\]/g, ":$1"),
+    // Transform optional params: {id} => {:id}
+    // Only pure \w param names,
+    // anything else treated as a path-to-regexp pattern and used as is.
+    // {some-id} treated as an optional static segment.
+    // use {some_id} for simple param syntax
+    // or {:some-id} pattern where :some is the param name and -id is a static segment.
+    (s) => s.replace(/\{(\w+)\}/g, "{:$1}"),
+    // Transform splat params: {...param} => {*param}
+    (s) => s.replace(/\{\.\.\./g, "{*"),
+    // Insert leading slash inside optional/splat groups.
+    // {:name} => {/:name}
+    // {*name} => {/*name}
+    (s) => {
+      return s.startsWith("{") ? s.replace(/^\{/, "{/") : s;
+    }
+  ];
+  const detectBareParams = (s) => {
+    let depth = 0;
+    for (const [i, ch] of [...s].entries()) {
+      if (ch === "{") {
+        depth += 1;
+      } else if (ch === "}") {
+        depth -= 1;
+      } else if (ch === ":" && depth === 0) {
+        const match = s.slice(i + 1).match(/^\w+/);
+        return match?.[0] || ":";
+      }
+    }
+    return;
+  };
+  const tokens = path.replace(/^index\/?/, "").split("/").flatMap((orig) => {
+    if (!orig.length) {
+      return [];
+    }
+    const bareParam = detectBareParams(orig);
+    if (bareParam === ":") {
+      throw new Error(
+        `${path} contains colons outside braces, use : only within {}`
+      );
+    } else if (bareParam) {
+      throw new Error(
+        `${path} contains bare params, use [${bareParam}] instead of :${bareParam}`
+      );
+    }
+    const pattern = patternTransforms.reduce((src, fn) => fn(src), orig);
+    const { tokens: tokens2 } = parse(pattern);
+    const parts = extractParts(tokens2, (val) => {
+      return /\W/.test(val) || /^\d/.test(val) ? [val.replace(/^\d+|\W/g, "_"), crc3(orig)].join("_") : val;
+    });
+    const isStatic = parts.length === 1 ? parts[0].type === "static" : false;
+    const isParam = parts.length === 1 ? parts[0].type === "param" : false;
+    const kind = isStatic ? "static" : isParam ? "param" : "mixed";
+    return [
+      {
+        kind,
+        orig,
+        pattern,
+        parts
+      }
+    ];
+  });
+  return [
+    tokens,
+    tokens.map(({ pattern }, i) => {
+      const next = tokens[i + 1];
+      if (!next || next.pattern.includes("/")) {
+        return pattern;
+      }
+      const slashRequired = tokens.slice(i + 1).some((e) => {
+        return e.parts.some((e2) => {
+          return e2.type === "static" || e2.kind === "required";
+        });
+      });
+      return slashRequired ? `${pattern}/` : pattern;
+    }).join("")
+  ];
+};
+var normalizeStaticValue = (value) => {
+  return value.replace(/\+/g, "\\\\+");
+};
+var sortRoutes = (a, b) => {
+  const aSpecificity = routeSpecificity(a.pathTokens);
+  const bSpecificity = routeSpecificity(b.pathTokens);
+  if (aSpecificity !== bSpecificity) {
+    return bSpecificity - aSpecificity;
+  }
+  if (a.pathTokens.length !== b.pathTokens.length) {
+    return a.pathTokens.length - b.pathTokens.length;
+  }
+  return a.name.localeCompare(b.name);
+};
+var paramWeight = (part) => {
+  return {
+    required: 2,
+    optional: 1,
+    splat: 0
+  }[part.kind];
+};
+var mixedSegmentWeight = (parts) => {
+  const hasSplat = parts.some((p) => {
+    return p.type === "param" ? p.kind === "splat" : false;
+  });
+  return hasSplat ? 0.5 : 3;
+};
+var segmentWeight = (token) => {
+  return {
+    static: 4,
+    mixed: mixedSegmentWeight(token.parts),
+    param: paramWeight(token.parts[0])
+  }[token.kind];
+};
+var routeSpecificity = (pathTokens) => {
+  return pathTokens.reduce((sum, token) => sum + segmentWeight(token), 0);
+};
+
+// src/routes/resolve.ts
+import { dirname as dirname3, join as join4, resolve as resolve4 } from "node:path";
+import { styleText as styleText3 } from "node:util";
+import crc4 from "crc/crc32";
+import mimeTypes from "mime-types";
+
+// src/routes/templates/resolved-types.hbs
+var resolved_types_default = "{{#each resolvedTypes}}\nexport type {{name}} = {{text}};\n{{/each}}\n";
+
+// src/routes/templates/types.hbs
+var types_default = '{{#each typeDeclarations}}{{text}}\n{{/each}}\n\nexport type {{params.id}} = {\n  {{#each paramsSchema}}\n  "{{name}}"{{#unless isRequired}}?{{/unless}}: {{#if refinement}}\n    {{refinement.text}},\n  {{else}}\n    {{#if isSplat}}Array<string>{{else}}string{{/if}},\n  {{/if}}\n  {{/each}}\n};\n\n{{#each validationTypes}}export type {{id}} = {{text}};\n{{/each}}\n';
+
+// src/routes/resolve.ts
+var resolverFactory = (sourceFolder, cacheFactory) => {
+  const {
+    //
+    generators = [],
+    refineTypeName = defaults.refineTypeName
+  } = sourceFolder.config;
+  const { typeResolverFactory, resolveRouteSignature } = astFactory();
+  const resolveTypes = generators.some(
+    (e) => getGeneratorMeta(e)?.resolveTypes
+  );
+  const {
+    //
+    literalTypesResolver,
+    getSourceFile,
+    refreshSourceFile
+  } = typeResolverFactory(sourceFolder);
+  return {
+    pageLayoutResolver(entry) {
+      const { name } = entry;
+      const handler = async () => {
+        return {
+          kind: "pageLayout",
+          entry
+        };
+      };
+      return { name, handler };
+    },
+    pageRouteResolver(entry) {
+      const { id, name, folder, file, fileFullpath, pathTokens, pathPattern } = entry;
+      const handler = async () => {
+        const entry2 = {
+          id,
+          name,
+          pathTokens,
+          pathPattern,
+          params: {
+            schema: pathTokens.flatMap((e) => {
+              return e.parts.filter((p) => p.type === "param");
+            })
+          },
+          folder,
+          file,
+          fileFullpath
+        };
+        return {
+          kind: "pageRoute",
+          entry: entry2
+        };
+      };
+      return { name, handler };
+    },
+    apiUseResolver(entry) {
+      const { name } = entry;
+      const handler = async () => {
+        return {
+          kind: "apiUse",
+          entry
+        };
+      };
+      return { name, handler };
+    },
+    apiRouteResolver(entry) {
+      const {
+        //
+        id,
+        name,
+        file,
+        folder,
+        fileFullpath,
+        pathTokens,
+        pathPattern
+      } = entry;
+      const handler = async (updatedFile) => {
+        const paramsSchema = pathTokens.flatMap(
+          (e) => {
+            return e.parts.flatMap((p) => {
+              return p.type === "param" ? [p] : [];
+            });
+          }
+        );
+        const optionalParams = paramsSchema.length ? paramsSchema.filter((e) => e.kind === "required").length === 0 : true;
+        const cacheStore = cacheFactory ? cacheFactory({ id, file, fileFullpath }, sourceFolder, {
+          resolveTypes
+        }) : void 0;
+        let cache = cacheStore ? await cacheStore.get({ validate: true }) : void 0;
+        if (!cache) {
+          if (updatedFile === fileFullpath) {
+            await refreshSourceFile(fileFullpath);
+          }
+          const {
+            typeDeclarations,
+            paramsRefinements,
+            methods,
+            validationDefinitions: validationDefinitions2,
+            referencedFiles = []
+          } = await resolveRouteSignature(
+            { id, name, fileFullpath, optionalParams },
+            {
+              withReferencedFiles: true,
+              sourceFile: getSourceFile(fileFullpath),
+              relpathResolver(path) {
+                return join4(
+                  sourceFolder.name,
+                  defaults.apiDir,
+                  dirname3(file),
+                  path
+                );
+              }
+            }
+          );
+          const validationTypes = validationDefinitions2.flatMap((def) => {
+            return def.target === "response" ? def.variants.flatMap(({ id: id2, body }) => {
+              return body ? [{ id: id2, text: body }] : [];
+            }) : [def.schema];
+          });
+          const numericParams = paramsRefinements ? paramsRefinements.flatMap(({ text, index }) => {
+            if (text === "number") {
+              const param = paramsSchema.at(index);
+              return param ? [param.name] : [];
+            }
+            return [];
+          }) : [];
+          const typesFile = pathResolver(sourceFolder).createPath.libApi(
+            dirname3(file),
+            "types.ts"
+          );
+          const params = {
+            id: ["ParamsT", crc4(name)].join(""),
+            schema: paramsSchema,
+            resolvedType: void 0
+          };
+          const typesFileContent = render(types_default, {
+            params,
+            paramsSchema: paramsSchema.map((param, index) => {
+              return {
+                ...param,
+                isRequired: param.kind === "required",
+                isSplat: param.kind === "splat",
+                refinement: paramsRefinements?.at(index)
+              };
+            }),
+            typeDeclarations,
+            validationTypes
+          });
+          const resolvedTypes = resolveTypes ? literalTypesResolver(typesFileContent, {
+            stripComments: true,
+            overrides: { [refineTypeName]: refineTypeName },
+            withProperties: [
+              params.id,
+              ...validationTypes.flatMap(({ id: id2 }) => id2)
+            ]
+          }) : void 0;
+          await renderToFile(
+            typesFile,
+            resolvedTypes ? resolved_types_default : typesFileContent,
+            { resolvedTypes }
+          );
+          params.resolvedType = resolvedTypes?.find(
+            (e) => e.name === params.id
+          );
+          cache = {
+            // placeholder values, if cacheFactory given,
+            // they will be replaced by persistCache
+            hash: 0,
+            referencedFiles: {},
+            // real values
+            params,
+            methods,
+            typeDeclarations,
+            numericParams,
+            validationDefinitions: validationDefinitions2.map((def) => {
+              return {
+                ...def,
+                ...def.target === "response" ? {
+                  variants: def.variants.map((variant) => {
+                    return {
+                      ...variant,
+                      resolvedType: resolvedTypes?.find(
+                        (e) => e.name === variant.id
+                      )
+                    };
+                  })
+                } : {
+                  schema: {
+                    ...def.schema,
+                    resolvedType: resolvedTypes?.find(
+                      (e) => e.name === def.schema.id
+                    )
+                  }
+                }
+              };
+            })
+          };
+          if (cacheStore) {
+            const { referencedFiles: _void, ...rest } = cache;
+            cache = await cacheStore.set({ ...rest, referencedFiles });
+          }
+        }
+        const validationDefinitions = cache.validationDefinitions.flatMap(
+          (def) => {
+            let augmentedDef = def;
+            if (def.target === "response") {
+              augmentedDef = {
+                ...def,
+                variants: def.variants.flatMap((variant, i) => {
+                  if (typeof variant.contentType !== "string") {
+                    return [variant];
+                  }
+                  if (variant.contentType.includes("/")) {
+                    return [variant];
+                  }
+                  const contentType = mimeTypes.lookup(variant.contentType);
+                  if (contentType === false) {
+                    console.warn(
+                      styleText3(
+                        ["bold", "red"],
+                        "\u2717 Failed resolving Response Content Type"
+                      )
+                    );
+                    console.warn(
+                      `  Invalid value provided for mime-types lookup - ${variant.contentType}`
+                    );
+                    console.warn(
+                      styleText3(
+                        ["cyan"],
+                        `  Response variant #${i} excluded from route schemas`
+                      )
+                    );
+                    console.warn(`  Route: ${name}; Method: ${def.method}`);
+                    console.warn();
+                    return [];
+                  }
+                  return [{ ...variant, contentType }];
+                })
+              };
+            } else if (def.contentType && !def.contentType.includes("/")) {
+              const contentType = mimeTypes.lookup(def.contentType);
+              if (contentType === false) {
+                console.warn(
+                  styleText3(
+                    ["bold", "red"],
+                    "\u2717 Failed resolving Response Content Type"
+                  )
+                );
+                console.warn(
+                  `  Invalid value provided for mime-types lookup - ${def.contentType}`
+                );
+                console.warn(`  Route: ${name}; Method: ${def.method}`);
+                console.warn();
+              } else {
+                augmentedDef = { ...def, contentType };
+              }
+            }
+            return augmentedDef ? [augmentedDef] : [];
+          }
+        );
+        const entry2 = {
+          id,
+          name,
+          pathTokens,
+          pathPattern,
+          params: cache.params,
+          numericParams: cache.numericParams,
+          optionalParams,
+          folder,
+          file,
+          fileFullpath,
+          methods: cache.methods,
+          typeDeclarations: cache.typeDeclarations,
+          validationDefinitions,
+          referencedFiles: Object.keys(cache.referencedFiles).map(
+            // expand referenced files path,
+            // they are stored as relative in cache
+            (e) => resolve4(sourceFolder.root, e)
+          )
+        };
+        return {
+          kind: "apiRoute",
+          entry: entry2
+        };
+      };
+      return { name, handler };
+    }
+  };
+};
+
+// src/routes/nesting.ts
+import { basename } from "node:path";
+var nestedRoutesFactory = (routeEntries) => {
+  const entryStack = structuredClone(routeEntries).sort(sortRoutes);
+  const transformEntries = (entries, parent) => {
+    return [...new Set(entries.map((e) => e.name))].flatMap((name) => {
+      const nameEntries = entryStack.flatMap(({ fileFullpath, ...entry }) => {
+        return entry.name === name ? [entry] : [];
+      });
+      const index = nameEntries.find(
+        (e) => basename(e.file).startsWith(PAGE_INDEX_BASENAME)
+      );
+      const layout = nameEntries.find(
+        (e) => basename(e.file).startsWith(PAGE_LAYOUT_BASENAME)
+      );
+      if (index || layout) {
+        return [
+          {
+            index: index ? {
+              ...index,
+              pathTokens: index.pathTokens.slice(
+                parent?.pathTokens.length || 0
+              )
+            } : void 0,
+            layout: layout ? {
+              ...layout,
+              pathTokens: layout.pathTokens.slice(
+                parent?.pathTokens.length || 0
+              )
+            } : void 0,
+            parent: parent?.name,
+            children: transformEntries(
+              findDescendantEntries(index || layout),
+              index || layout
+            )
+          }
+        ];
+      }
+      return [];
+    });
+  };
+  const findDescendantEntries = ({
+    name,
+    pathTokens
+  }) => {
+    const potentialChildren = entryStack.filter((entry) => {
+      if (entry.pathTokens.length <= pathTokens.length) {
+        return false;
+      }
+      if (!entry.name.startsWith(`${name}/`)) {
+        return false;
+      }
+      return true;
+    });
+    return potentialChildren.filter((child) => {
+      const hasIntermediateRoute = potentialChildren.some((intermediate) => {
+        if (intermediate === child) {
+          return false;
+        }
+        if (intermediate.pathTokens.length <= pathTokens.length) {
+          return false;
+        }
+        if (intermediate.pathTokens.length >= child.pathTokens.length) {
+          return false;
+        }
+        return child.name.startsWith(`${intermediate.name}/`);
+      });
+      return !hasIntermediateRoute;
+    });
+  };
+  const rootEntries = entryStack.filter((entry) => {
+    const hasParent = entryStack.some((potential) => {
+      if (potential === entry) {
+        return false;
+      }
+      if (potential.pathTokens.length >= entry.pathTokens.length) {
+        return false;
+      }
+      return entry.name.startsWith(`${potential.name}/`);
+    });
+    return !hasParent;
+  });
+  return transformEntries(rootEntries);
+};
+
+// src/routes/index.ts
+var routesFactory = async (sourceFolder, cacheFactory) => {
+  const {
+    apiRouteResolver,
+    apiUseResolver,
+    pageRouteResolver,
+    pageLayoutResolver
+  } = resolverFactory(sourceFolder, cacheFactory);
+  const resolversFactory = (routeFiles2) => {
+    const resolvers = /* @__PURE__ */ new Map();
+    const entries = routeFiles2.flatMap((file) => {
+      const entry = createRouteEntry(file, sourceFolder);
+      return entry ? [entry] : [];
+    });
+    for (const entry of entries) {
+      if (entry.folder === defaults.apiDir) {
+        if (isApiRoute(entry.file)) {
+          resolvers.set(entry.fileFullpath, apiRouteResolver(entry));
+        } else if (isApiUse(entry.file)) {
+          resolvers.set(entry.fileFullpath, apiUseResolver(entry));
+        }
+      } else if (entry.folder === defaults.pagesDir) {
+        if (isPageRoute(entry.file)) {
+          resolvers.set(entry.fileFullpath, pageRouteResolver(entry));
+        } else if (isPageLayout(entry.file)) {
+          resolvers.set(entry.fileFullpath, pageLayoutResolver(entry));
+        }
+      }
+    }
+    return resolvers;
+  };
+  const routeFiles = await scanRoutes(sourceFolder);
+  return {
+    resolvers: resolversFactory(routeFiles),
+    resolversFactory
+  };
+};
+
+// src/spinner.ts
+import { Spinner } from "@topcli/spinner";
+var spinnerFactory = (startText) => {
+  const spinner = new Spinner().start(startText);
+  let _text = startText;
+  return {
+    text(text) {
+      _text = text;
+      spinner.text = text;
+    },
+    append(text) {
+      spinner.text = `${_text} \u203A ${text}`;
+    },
+    succeed(text) {
+      if (text) {
+        this.append(text);
+      } else {
+        this.text(_text);
+      }
+      spinner.succeed();
+    },
+    failed(text) {
+      if (text) {
+        this.text([_text, text].join("\n"));
+      }
+      spinner.failed();
+    }
+  };
+};
+var withSpinner = (text, pipe, spinner) => pipe(spinner || spinnerFactory(text));
+
+// src/typebox.ts
+var typeboxLiteralText = (text, sourceFolder) => {
+  const { refineTypeName = defaults.refineTypeName } = sourceFolder.config;
+  return [
+    // Escape backticks for safe use in template literals
+    [/(?<!\\)`/g, "\\`"],
+    // Escape $ for safe use in template literals
+    [/(?<!\\)\$\{/g, "\\${"],
+    /**
+     * TypeBox's built-in `Options` type is not configurable.
+     * To allow a custom type name, exposing `refineTypeName` option,
+     * defaulted to VRefine, then renaming it to `Options`.
+     * */
+    [new RegExp(`\\b${refineTypeName}\\s*<`, "g"), "Options<"]
+  ].reduce((text2, [a, b]) => text2.replace(a, b), text);
+};
+export {
+  API_INDEX_BASENAME,
+  API_INDEX_PATTERN,
+  API_USE_BASENAME,
+  API_USE_PATTERN,
+  GENERATOR_META,
+  PAGE_INDEX_BASENAME,
+  PAGE_INDEX_PATTERN,
+  PAGE_LAYOUT_BASENAME,
+  PAGE_LAYOUT_PATTERN,
+  astFactory,
+  createRouteEntry,
+  createTsconfigPaths,
+  defaults,
+  defineGenerator,
+  defineGeneratorFactory,
+  getGeneratorMeta,
+  isApiRoute,
+  isApiUse,
+  isGenerator,
+  isPageLayout,
+  isPageRoute,
+  isRouteFile,
+  nestedRoutesFactory,
+  normalizeStaticValue,
+  pathExists,
+  pathResolver,
+  pathTokensFactory,
+  render,
+  renderFactory,
+  renderHelpers,
+  renderToFile,
+  routesFactory,
+  scanRoutes,
+  sortRoutes,
+  spinnerFactory,
+  typeboxLiteralText,
+  withSpinner
+};
+//# sourceMappingURL=index.js.map