@revealui/core 0.0.1-pre.0

package/dist/core/router/resolvePrecedence.ts

@@ -0,0 +1,128 @@
+export { resolvePrecendence as resolvePrecedence }
+// export type { RouteMatch }
+
+import type { RouteType } from "./loadPageRoutes.js"
+import {
+  analyzeRouteString,
+  isStaticRouteString,
+} from "./resolveRouteString.js"
+import { higherFirst, lowerFirst, makeFirst } from "./utils.js"
+
+type RouteMatch = {
+  precedence?: number | null
+  routeString?: string
+  routeType: RouteType
+}
+
+// See https://reveal.dev/route-function#precedence
+function resolvePrecendence<T extends RouteMatch>(routeMatches: T[]): void {
+  // prettier-ignore
+  // biome-ignore format:
+  routeMatches
+    .sort(sortMatches)
+    .sort(makeFirst((routeMatch) => routeMatch.routeType === 'FUNCTION' && !!routeMatch.precedence && routeMatch.precedence < 0))
+    .sort(makeFirst((routeMatch) => routeMatch.routeType === 'STRING'   && isStaticRouteString(routeMatch.routeString!) === false))
+    .sort(makeFirst((routeMatch) => routeMatch.routeType === 'FUNCTION' && !routeMatch.precedence))
+    .sort(makeFirst((routeMatch) => routeMatch.routeType === 'STRING'   && isStaticRouteString(routeMatch.routeString!) === true))
+    .sort(makeFirst((routeMatch) => routeMatch.routeType === 'FILESYSTEM'))
+    .sort(makeFirst((routeMatch) => routeMatch.routeType === 'FUNCTION' && !!routeMatch.precedence && routeMatch.precedence > 0))
+}
+
+// -1 => routeMatch1 higher precedence
+// +1 => routeMatch2 higher precedence
+function sortMatches(
+  routeMatch1: RouteMatch,
+  routeMatch2: RouteMatch
+): 0 | -1 | 1 {
+  {
+    const precedence1 = routeMatch1.precedence ?? 0
+    const precedence2 = routeMatch2.precedence ?? 0
+    if (precedence1 !== precedence2) {
+      return precedence1 > precedence2 ? -1 : 1
+    }
+  }
+
+  if (!routeMatch2.routeString) {
+    return 0
+  }
+  if (!routeMatch1.routeString) {
+    return 0
+  }
+
+  /* DEBUG
+  console.log('routeMatch1.routeString', routeMatch1.routeString)
+  console.log('routeMatch2.routeString', routeMatch2.routeString)
+  console.log('parseRouteString(routeMatch1.routeString)', parseRouteString(routeMatch1.routeString))
+  console.log('parseRouteString(routeMatch2.routeString)', parseRouteString(routeMatch2.routeString))
+  //*/
+
+  // Return route with highest number of static path segments at beginning first
+  {
+    const getValue = (routeString: string) =>
+      analyzeRouteString(routeString).numberOfStaticPartsBeginning
+    const result = higherFirst(getValue)(
+      routeMatch1.routeString,
+      routeMatch2.routeString
+    )
+    if (result !== 0) {
+      /* DEBUG
+      console.log('analyzeRouteString(routeMatch1.routeString).numberOfStaticPartsBeginning', getValue(routeMatch1.routeString))
+      console.log('analyzeRouteString(routeMatch2.routeString).numberOfStaticPartsBeginning', getValue(routeMatch2.routeString))
+      //*/
+      return result
+    }
+  }
+
+  // Return route with highest number of static path segments in total first
+  {
+    const getValue = (routeString: string) =>
+      analyzeRouteString(routeString).numberOfStaticParts
+    const result = higherFirst(getValue)(
+      routeMatch1.routeString,
+      routeMatch2.routeString
+    )
+    if (result !== 0) {
+      /* DEBUG
+      console.log('analyzeRouteString(routeMatch1.routeString).numberOfStaticParts', getValue(routeMatch1.routeString))
+      console.log('analyzeRouteString(routeMatch2.routeString).numberOfStaticParts', getValue(routeMatch2.routeString))
+      //*/
+      return result
+    }
+  }
+
+  // Return route with least amount of globs first
+  {
+    const getValue = (routeString: string) =>
+      analyzeRouteString(routeString).numberOfGlobs
+    const result = lowerFirst(getValue)(
+      routeMatch1.routeString,
+      routeMatch2.routeString
+    )
+    if (result !== 0) {
+      /* DEBUG
+      console.log('analyzeRouteString(routeMatch1.routeString).numberOfGlobs', getValue(routeMatch1.routeString))
+      console.log('analyzeRouteString(routeMatch2.routeString).numberOfGlobs', getValue(routeMatch2.routeString))
+      //*/
+      return result
+    }
+  }
+
+  // Return route with highest number of parameters first
+  {
+    const getValue = (routeString: string) =>
+      analyzeRouteString(routeString).numberOfParams
+    const result = higherFirst(getValue)(
+      routeMatch1.routeString,
+      routeMatch2.routeString
+    )
+    if (result !== 0) {
+      /* DEBUG
+      console.log('analyzeRouteString(routeMatch1.routeString).numberOfParams', getValue(routeMatch1.routeString))
+      console.log('analyzeRouteString(routeMatch2.routeString).numberOfParams', getValue(routeMatch2.routeString))
+      //*/
+      return result
+    }
+  }
+
+  return 0
+}

package/dist/core/router/resolveRoute.ts

@@ -0,0 +1,29 @@
+export { resolveRoute };
+
+import { assertUsage } from "./utils.js";
+import { resolveRouteString } from "./resolveRouteString.js";
+import pc from "@brillout/picocolors";
+
+function resolveRoute(
+  routeString: string,
+  urlPathname: string,
+): { match: boolean; routeParams: Record<string, string> } {
+  const errMsg = (
+    propName: "routeString" | "urlPathname",
+    msg = "a non-empty string",
+  ) =>
+    `[resolveRoute(routeString, urlPathname)] ${pc.cyan(propName)} should be ` +
+    msg;
+  assertUsage(routeString, errMsg("routeString"), { showStackTrace: true });
+  assertUsage(urlPathname, errMsg("urlPathname"), { showStackTrace: true });
+  assertUsage(
+    urlPathname.startsWith("/"),
+    errMsg("urlPathname", "pageContext.urlPathname"),
+    { showStackTrace: true },
+  );
+  const result = resolveRouteString(routeString, urlPathname);
+  return {
+    match: !!result,
+    routeParams: result?.routeParams ?? {},
+  };
+}

package/dist/core/router/resolveRouteFunction.ts

@@ -0,0 +1,193 @@
+export { assertRouteParams, resolveRouteFunction }
+
+import pc from "@brillout/picocolors"
+
+import {
+  assertPageContextUrl,
+  PageContextUrlInternal,
+} from "../processing/getters/getPageContextUrlComputed.js"
+import { assert, assertUsage, hasProp, isPlainObject } from "./utils.js"
+
+async function resolveRouteFunction(
+  routeFunction: (pageContext: PageContextUrlInternal) => unknown,
+  pageContext: PageContextUrlInternal,
+  routeDefinedAtString: string
+): Promise<null | {
+  precedence: number | null
+  routeParams: Record<string, string>
+}> {
+  assertPageContextUrl(pageContext)
+
+  const result = await routeFunction(pageContext) // Await the routeFunction
+
+  assertUsage(
+    isPlainObject(result),
+    `The Route Function ${routeDefinedAtString} should return a boolean or a plain JavaScript object (but it's ${pc.cyan(
+      `typeof result === ${JSON.stringify(typeof result)}`
+    )} instead)`
+  )
+
+  if ("match" in result) {
+    const { match } = result
+    assertUsage(
+      typeof match === "boolean",
+      `The ${pc.cyan("match")} value returned by the Route Function ${routeDefinedAtString} should be a boolean.`
+    )
+    if (!match) {
+      console.log("No match in result found")
+      return null // Return null if no match found
+    }
+  }
+
+  let precedence: number | null = null
+  if ("precedence" in result) {
+    precedence = (result as { precedence: number }).precedence
+    assertUsage(
+      typeof precedence === "number",
+      `The ${pc.cyan("precedence")} value returned by the Route Function ${routeDefinedAtString} should be a number.`
+    )
+  }
+
+  assertRouteParams(
+    result,
+    `The ${pc.cyan("routeParams")} object returned by the Route Function ${routeDefinedAtString} should`
+  )
+  const routeParams: Record<string, string> = result.routeParams || {}
+
+  assertUsage(
+    !("pageContext" in result),
+    `Providing ${pc.cyan(
+      "pageContext"
+    )} in Route Functions is prohibited, see https://reveal.dev/route-function#cannot-provide-pagecontext`
+  )
+
+  assert(isPlainObject(routeParams))
+  Object.keys(result).forEach((key) => {
+    assertUsage(
+      key === "match" || key === "routeParams" || key === "precedence",
+      `The Route Function ${routeDefinedAtString} returned an object with an unknown property ${pc.cyan(
+        key
+      )} (the known properties are ${pc.cyan("match")}, ${pc.cyan("routeParams")}, and ${pc.cyan("precedence")})`
+    )
+  })
+
+  return {
+    precedence,
+    routeParams,
+  }
+}
+
+function assertRouteParams<T>(
+  result: T,
+  errPrefix: string
+): asserts result is T & { routeParams?: Record<string, string> } {
+  assert(errPrefix.endsWith(" should"))
+  if (!hasProp(result, "routeParams")) {
+    return
+  }
+  assertUsage(
+    hasProp(result, "routeParams", "string{}"),
+    `${errPrefix} be an object holding string values.`
+  )
+}
+
+// export { resolveRouteFunction };
+// export { assertRouteParams };
+// // export { assertSyncRouting };
+// // export { warnDeprecatedAllowKey };
+
+// import {
+//   assertPageContextUrl,
+//   PageContextUrlInternal,
+// } from "../getPageContextUrlComputed.js";
+// import {
+//   assert,
+//   assertUsage,
+//   hasProp,
+//   isPlainObject,
+// } from "./utils.js";
+// import pc from "@brillout/picocolors";
+
+// function resolveRouteFunction(
+//   routeFunction: Function,
+//   pageContext: PageContextUrlInternal,
+//   routeDefinedAtString: string,
+// ): Promise<null | {
+//   precedence: number | null;
+//   routeParams: Record<string, string>;
+// }> {
+//   assertPageContextUrl(pageContext);
+//   let result: unknown = routeFunction(pageContext);
+
+//   assertUsage(
+//     isPlainObject(result),
+//     `The Route Function ${routeDefinedAtString} should return a boolean or a plain JavaScript object (but it's ${pc.cyan(
+//       `typeof result === ${JSON.stringify(typeof result)}`,
+//     )} instead)`,
+//   );
+
+//   // AFAICT this return interface is superfluous. Should we soft-deprecate it and remove it?
+//   if ("match" in result) {
+//     const { match } = result;
+//     assertUsage(
+//       typeof match === "boolean",
+//       `The ${pc.cyan("match")} value returned by the Route Function ${routeDefinedAtString} should be a boolean.`,
+//     );
+//     if (!match) {
+
+//       console.log("No match in result found")
+//     }
+//   }
+
+//   let precedence = null;
+//   if ("precedence" in result) {
+//     precedence = result.precedence;
+//     assertUsage(
+//       typeof precedence === "number",
+//       `The ${pc.cyan("precedence")} value returned by the Route Function ${routeDefinedAtString} should be a number.`,
+//     );
+//   }
+
+//   assertRouteParams(
+//     result,
+//     `The ${pc.cyan("routeParams")} object returned by the Route Function ${routeDefinedAtString} should`,
+//   );
+//   const routeParams: Record<string, string> = result.routeParams || {};
+
+//   assertUsage(
+//     !("pageContext" in result),
+//     `Providing ${pc.cyan(
+//       "pageContext",
+//     )} in Route Functions is prohibited, see https://reveal.dev/route-function#cannot-provide-pagecontext`,
+//   );
+
+//   assert(isPlainObject(routeParams));
+//   Object.keys(result).forEach((key) => {
+//     assertUsage(
+//       key === "match" || key === "routeParams" || key === "precedence",
+//       `The Route Function ${routeDefinedAtString} returned an object with an unknown property ${pc.cyan(
+//         key,
+//       )} (the known properties are ${pc.cyan("match")}, ${pc.cyan("routeParams")}, and ${pc.cyan("precedence")})`,
+//     );
+//   });
+
+//   return {
+//     precedence,
+//     routeParams,
+//   };
+// }
+
+// function assertRouteParams<T>(
+//   result: T,
+//   errPrefix: string,
+// ): asserts result is T & { routeParams?: Record<string, string> } {
+//   assert(errPrefix.endsWith(" should"));
+//   if (!hasProp(result, "routeParams")) {
+//     return;
+//   }
+//   assert(errPrefix.endsWith(" should"));
+//   assertUsage(
+//     hasProp(result, "routeParams", "string{}"),
+//     `${errPrefix} be an object holding string values.`,
+//   );
+// }

package/dist/core/router/resolveRouteString.ts

@@ -0,0 +1,204 @@
+export {
+  analyzeRouteString,
+  assertRouteString,
+  getRouteStringParameterList,
+  getUrlFromRouteString,
+  isStaticRouteString,
+  resolveRouteString,
+};
+
+import pc from "@brillout/picocolors";
+import { assert } from "../gaurds/assertions/assert/base";
+import { assertUsage } from "../gaurds/assertions/assertUsage/base";
+import { isBrowser } from "../gaurds/validators/isBrowser";
+import { escapeRegex } from "../utils/string/escapeRegex";
+
+const PARAM_TOKEN_NEW = "@";
+
+function assertRouteString(
+  routeString: string,
+  errPrefix: `${string}Invalid` | `${string}invalid` = "Invalid",
+) {
+  let errPrefix2 =
+    `${errPrefix} Route String ${highlight(routeString)}` as const;
+  assertUsage(
+    routeString !== "",
+    `${errPrefix2} (empty string): set it to ${highlight("/")} instead`,
+  );
+  assertUsage(
+    ["/", "*"].includes(routeString[0]!),
+    `${errPrefix2}: it should start with ${highlight("/")} or ${highlight("*")}`,
+  );
+  assertUsage(
+    !routeString.includes("**"),
+    `${errPrefix2}: set it to ${highlight(routeString.split("**").join("*"))} instead`,
+  );
+}
+
+function resolveRouteString(
+  routeString: string,
+  urlPathname: string,
+): null | { routeParams: Record<string, string> } {
+  assertRouteString(routeString);
+
+  const segments = parseRouteString(routeString);
+  const routeRegexStrInner: string = segments
+    .map((segment) => {
+      if (segment.param) {
+        return "[^/]+";
+      }
+      if (segment.glob) {
+        return ".*";
+      }
+      // segment.static
+      return escapeRegex(segment.static!);
+    })
+    .map((s) => `(${s})`)
+    .join("");
+  const routeRegex = new RegExp(`^${routeRegexStrInner}/?$`);
+  const routeRegexMatch = urlPathname.match(routeRegex);
+
+  /* DEBUG
+  console.log()
+  console.log('routeString', routeString)
+  console.log('urlPathname', urlPathname)
+  console.log('routeSegments', segments)
+  console.log('routeRegex', routeRegex)
+  console.log('routeRegexMatch', routeRegexMatch)
+  //*/
+
+  if (!routeRegexMatch) return null;
+
+  const routeParams: Record<string, string> = {};
+  const [_, ...segmentsValue] = routeRegexMatch;
+  let globIdx = 0;
+  const hasMultipleGlobs =
+    segments.filter((segment) => segment.glob).length > 1;
+  segments.forEach((segment, i) => {
+    let val = segmentsValue[i]!;
+    if (segment.param) {
+      routeParams[segment.param] = val;
+    }
+    if (segment.glob) {
+      const param = `*${hasMultipleGlobs ? ++globIdx : ""}` as const;
+      routeParams[param] = val;
+    }
+  });
+  return { routeParams };
+}
+type Segment =
+  | {
+      glob: true;
+      static?: undefined;
+      param?: undefined;
+    }
+  | {
+      glob?: undefined;
+      static: string;
+      param?: undefined;
+    }
+  | {
+      glob?: undefined;
+      static?: undefined;
+      param: string;
+    };
+function parseRouteString(routeString: string) {
+  const segments: Segment[] = [];
+  const pushStatic = (s: string) => {
+    const segmentLast = segments[segments.length - 1];
+    if (segmentLast?.static) {
+      segmentLast.static += s;
+    } else {
+      segments.push({ static: s });
+    }
+  };
+  const parts = routeString.split("/");
+  parts.forEach((s, i) => {
+    if (i !== 0) pushStatic("/");
+    if (isParam(s)) {
+      segments.push({ param: s.slice(1) });
+    } else {
+      if (
+        s === "*" &&
+        i === parts.length - 1 &&
+        routeString !== "*" &&
+        routeString !== "/*"
+      ) {
+        segments.push({ glob: true });
+      } else {
+        s.split("*").forEach((s, i) => {
+          if (i !== 0) segments.push({ glob: true });
+          if (s !== "") {
+            pushStatic(s);
+          }
+        });
+      }
+    }
+  });
+  return segments;
+}
+
+function getRouteStringParameterList(routeString: string): string[] {
+  const routeParameterList: string[] = [];
+  const segments = parseRouteString(routeString);
+  segments.forEach((segment) => {
+    if (segment.param) routeParameterList.push(segment.param);
+  });
+  return routeParameterList;
+}
+
+function getUrlFromRouteString(routeString: string): null | string {
+  if (isStaticRouteString(routeString)) {
+    const url = routeString;
+    return url;
+  }
+  return null;
+}
+
+function analyzeRouteString(routeString: string) {
+  const segments = parseRouteString(routeString);
+
+  const countStaticParts = (s: string | undefined): number =>
+    s?.split("/").filter(Boolean).length || 0;
+
+  let numberOfStaticPartsBeginning = 0;
+  for (const segment of segments) {
+    if (!segment.static) break;
+    numberOfStaticPartsBeginning += countStaticParts(segment.static);
+  }
+
+  const numberOfStaticParts = segments
+    .map((s) => countStaticParts(s.static))
+    .reduce((sum, a) => sum + a, 0);
+  const numberOfParams = segments.filter((s) => s.param).length;
+  const numberOfGlobs = segments.filter((s) => s.glob).length;
+
+  return {
+    numberOfStaticPartsBeginning,
+    numberOfStaticParts,
+    numberOfParams,
+    numberOfGlobs,
+  };
+}
+
+function isParam(routeSegment: string) {
+  return routeSegment.startsWith(PARAM_TOKEN_NEW);
+}
+
+function isStaticRouteString(routeString: string): boolean {
+  const url = routeString;
+  const match = resolveRouteString(routeString, url);
+  assert(match);
+  return Object.keys(match.routeParams).length === 0;
+}
+
+function highlight(routeString: string) {
+  if (isBrowser()) {
+    return `'${routeString}'`;
+  } else {
+    if (routeString === "") {
+      routeString = "''";
+    }
+    return pc.cyan(routeString);
+  }
+}

package/dist/core/router/resolveRouteUtils.ts

@@ -0,0 +1,77 @@
+import { PageContextUrlInternal } from "../processing/getters/getPageContextUrlComputed";
+import { assert } from "../utils";
+
+export type RouteMatchResult = {
+  routeParams: Record<string, string>;
+  precedence?: number | null;
+};
+
+/**
+ * Matches a URL against a route string pattern.
+ * @param routeString - The route string pattern (e.g., "/about/:section").
+ * @param urlPathname - The URL pathname to match.
+ * @returns - The route match result with extracted parameters, or null if no match.
+ */
+export function resolveRouteString(
+  routeString: string,
+  urlPathname: string,
+): RouteMatchResult | null {
+  const routeParts = routeString.split("/").filter(Boolean);
+  const urlParts = urlPathname.split("/").filter(Boolean);
+
+  if (routeParts.length !== urlParts.length) {
+    return null;
+  }
+
+  const routeParams: Record<string, string> = {};
+  for (let i = 0; i < routeParts.length; i++) {
+    const routePart = routeParts[i];
+    const urlPart = urlParts[i];
+
+    if (routePart && routePart.startsWith(":")) {
+      // Dynamic segment, e.g., ":id"
+      const paramName = routePart.slice(1);
+      if (urlPart !== undefined) {
+        routeParams[paramName] = urlPart;
+      } else {
+        return null;
+      }
+    } else if (routePart !== urlPart) {
+      // Static segment mismatch
+      return null;
+    }
+  }
+
+  return { routeParams };
+}
+
+/**
+ * Executes a route function to determine if it matches the current URL.
+ * @param routeFunction - The route function to evaluate.
+ * @param pageContext - The current page context.
+ * @param definedAtString - (Optional) Location where the route is defined for debugging.
+ * @returns - The route match result if the function returns a match, or null otherwise.
+ */
+export async function resolveRouteFunction(
+  routeFunction: (pageContext: PageContextUrlInternal) => unknown,
+  pageContext: PageContextUrlInternal,
+  definedAtString?: string,
+): Promise<RouteMatchResult | null> {
+  try {
+    const result = await routeFunction(pageContext);
+
+    if (typeof result === "object" && result !== null) {
+      const { routeParams, precedence } = result as RouteMatchResult;
+      if (routeParams && typeof routeParams === "object") {
+        return { routeParams, precedence: precedence ?? null };
+      }
+    }
+    return null;
+  } catch (error) {
+    console.error(
+      `Error in route function defined at ${definedAtString || "unknown"}:`,
+      error,
+    );
+    return null;
+  }
+}

package/dist/core/router/resolveUrlPathname.ts

@@ -0,0 +1,67 @@
+export { resolveUrlPathname };
+
+import { assert } from "../gaurds/assertions/assert/index.js";
+import { assertIsNotBrowser } from "../gaurds/assertions/assertIsNotBrowser/index.js";
+import { assertUsage } from "../gaurds/assertions/assertUsage/index.js";
+
+assertIsNotBrowser(); // Don't bloat the client
+
+type Part =
+  | {
+      type: "ROUTE_STRING";
+      val: string;
+    }
+  | {
+      type: "URL";
+      val: string;
+    };
+/** Given a `routeString` and `routeParams`, resolve `urlPathname`.
+ *
+ * Basically, the correct implementation of following:
+ * ```js
+ * let urlPathname = routeString
+ * Object.entries(routeParams).forEach(([key, val]) => {
+ *   urlPathname = urlPathname.replaceAll(key, val)
+ * })
+ * ```
+ */
+function resolveUrlPathname(
+  routeString: string,
+  routeParams: Record<string, string>,
+): string {
+  let parts: Part[] = [{ val: routeString, type: "ROUTE_STRING" }];
+
+  Object.entries(routeParams).forEach(([key, val]) => {
+    if (key.startsWith("*")) {
+      assert(key === "*" || /\d+/.test(key.slice(1)));
+      assertUsage(
+        key === "*",
+        "Resolving URL with multiple globs isn't implemented yet",
+      );
+    } else {
+      key = `@${key}`;
+    }
+    parts = parts
+      .map((part) => {
+        if (part.type === "URL") {
+          return part;
+        } else {
+          return part.val
+            .split(key)
+            .map((rest, i) => {
+              const partURL = { val, type: "URL" as const };
+              const partRouteString = {
+                val: rest,
+                type: "ROUTE_STRING" as const,
+              };
+              return i === 0 ? [partRouteString] : [partURL, partRouteString];
+            })
+            .flat();
+        }
+      })
+      .flat();
+  });
+
+  const urlPathname = parts.map((p) => p.val).join("");
+  return urlPathname;
+}