interface Options {
  defaultRoute: string | DefaultRouteCallback;
  defaultParams: Params | DefaultParamsCallback;
  trailingSlash: "strict" | "never" | "always" | "preserve";
  caseSensitive: boolean;
  urlParamsEncoding: "default" | "uri" | "uriComponent" | "none";
  queryParamsMode: QueryParamsMode;
  queryParams?: QueryParamsOptions;
  allowNotFound: boolean;
  rewritePathOnMatch: boolean;
  logger?: Partial<LoggerConfig>;
  limits?: Partial<LimitsConfig>;
}

type DefaultRouteCallback<Dependencies = object> = (
  getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K],
) => string;

type DefaultParamsCallback<Dependencies = object> = (
  getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K],
) => Params;

// Static value
const router = createRouter(routes, {
  defaultRoute: "home",
});

// On start with empty path, navigates to "home"
await router.start("");

import { createRouter } from "@real-router/core";
import { getDependenciesApi } from "@real-router/core/api";

// Dynamic callback — resolved at point of use (start, navigateToDefault)
const router = createRouter<MyDependencies>(routes, {
  defaultRoute: (getDependency) => {
    const role = getDependency("userRole");
    return role === "admin" ? "admin.dashboard" : "home";
  },
});

getDependenciesApi(router).set("userRole", "admin");
await router.start(""); // navigates to "admin.dashboard"

// Static value
const router = createRouter(routes, {
  defaultRoute: "users",
  defaultParams: { page: "1", sort: "name" },
});

// Dynamic callback
const router = createRouter<MyDependencies>(routes, {
  defaultRoute: "users.view",
  defaultParams: (getDependency) => ({
    id: getDependency("currentUserId"),
  }),
});

getDependenciesApi(router).set("currentUserId", "42");
await router.navigateToDefault(); // navigates to "users.view" with { id: "42" }

const router = createRouter(routes, {
  trailingSlash: "never",
});

// /users/ becomes /users

// defaults: trailingSlash: "preserve", rewritePathOnMatch: true
api.matchPath("/users/"); // state.path === "/users/"  — trailing kept
api.matchPath("/users");  // state.path === "/users"   — no trailing added

const router = createRouter(routes, {
  caseSensitive: true,
});

// "Users" and "users" are different routes

type QueryParamsMode = "default" | "strict" | "loose";

interface QueryParamsOptions {
  arrayFormat?: "none" | "brackets" | "index" | "comma";
  booleanFormat?: "none" | "auto" | "empty-true";
  nullFormat?: "default" | "hidden";
  numberFormat?: "none" | "auto";
}

const router = createRouter(routes, {
  queryParams: { numberFormat: "auto" },
});

// /users?page=3&limit=20&sort=name
// → state.params: { page: 3, limit: 20, sort: "name" }

router.navigate("search", { q: "hello", page: undefined, sort: null, filter: "" });
// URL: /search?q=hello&sort&filter=
// state.params: { q: "hello", sort: null, filter: "" }  // "page" absent

const router = createRouter(routes, {
  allowNotFound: true,
});

// Navigation to unknown route creates "@@router/UNKNOWN_ROUTE" state
// instead of throwing ROUTE_NOT_FOUND error

router.usePlugin(() => ({
  onTransitionError(_toState, _fromState, err) {
    if (err.code === "ROUTE_NOT_FOUND") {
      void router.navigateToDefault({ replace: true });
    }
  },
}));

interface LoggerConfig {
  level: "all" | "warn-error" | "error-only" | "none";
  callback?: (
    level: "log" | "warn" | "error",
    context: string,
    message: string,
  ) => void;
  callbackIgnoresLevel?: boolean;
}

const router = createRouter(routes, {
  logger: {
    level: "error-only", // Only log errors
    callback: (level, context, message) => {
      if (level === "error") {
        Sentry.captureMessage(`[${context}] ${message}`);
      }
    },
    callbackIgnoresLevel: true, // Callback receives all logs
  },
});

import { createRouter } from "@real-router/core";

const router = createRouter(routes, {
  defaultRoute: "home",
  trailingSlash: "never",
  allowNotFound: true,
});

const router = createRouter(routes, {
  defaultRoute: "dashboard",
  defaultParams: { view: "overview" },
  trailingSlash: "never",
  caseSensitive: false,
  urlParamsEncoding: "default",
  queryParamsMode: "loose",
  queryParams: {
    arrayFormat: "brackets",
    booleanFormat: "auto",
    nullFormat: "hidden",
    numberFormat: "auto",
  },
  allowNotFound: true,
  rewritePathOnMatch: false,
  logger: {
    level: "warn-error",
  },
});

const router = createRouter(routes, {
  defaultRoute: "home",
  allowNotFound: true,
  logger: {
    level: "none", // Disable console output
    callback: (level, context, message) => {
      // Send to monitoring service
      if (level === "error") {
        errorTracker.capture(`[${context}] ${message}`);
      }
    },
    callbackIgnoresLevel: true,
  },
});

const router = createRouter(routes, {
  limits: {
    maxPlugins: 100,
    maxDependencies: 200,
  },
});

createRouter(routes, {
  limits: { maxPlugins: 100 }, // Only override maxPlugins
});

import { getPluginApi } from "@real-router/core/api";

// Get all options (returns a copy)
const options = getPluginApi(router).getOptions();