Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,103 @@
|
||||
import { describe, expect, test } from "vitest";
|
||||
|
||||
import CanonicalUrlUtils, { adminPath, adminUrl, apiPath, apiUrl, appPath, appUrl } from "./index.js";
|
||||
|
||||
describe("canonical URL package contract", () => {
|
||||
test("builds host-aware app, admin, and API paths by default", () => {
|
||||
expect(appPath({ tenantSlug: "acme", path: "dashboard" })).toBe("/acme/dashboard");
|
||||
expect(adminPath("accounts")).toBe("/accounts");
|
||||
expect(apiPath("users")).toBe("/v1/users");
|
||||
});
|
||||
|
||||
test("builds host-aware app, admin, and API paths", () => {
|
||||
expect(appPath({ tenantSlug: "acme", path: "dashboard", mode: "host-aware" })).toBe("/acme/dashboard");
|
||||
expect(adminPath("accounts", { mode: "host-aware" })).toBe("/accounts");
|
||||
expect(apiPath("users", { mode: "host-aware" })).toBe("/v1/users");
|
||||
});
|
||||
|
||||
test("normalizes slashes and preserves query strings", () => {
|
||||
expect(appPath({ tenantSlug: "acme", path: "//settings///users/?tab=billing" })).toBe("/acme/settings/users?tab=billing");
|
||||
expect(appPath({ tenantSlug: "acme" })).toBe("/acme");
|
||||
expect(appPath({ tenantSlug: "acme", path: "?tab=billing" })).toBe("/acme?tab=billing");
|
||||
expect(adminPath()).toBe("/");
|
||||
expect(adminPath("/")).toBe("/");
|
||||
expect(adminPath({ path: "///settings//profile///" })).toBe("/settings/profile");
|
||||
expect(apiPath({ path: "/webhooks//inbound#email", mode: "host-aware" })).toBe("/v1/webhooks/inbound#email");
|
||||
expect(apiPath("/v1/health")).toBe("/v1/health");
|
||||
expect(apiPath("/api/v1/health")).toBe("/v1/health");
|
||||
expect(apiPath("/api/v1?active=true")).toBe("/v1?active=true");
|
||||
expect(apiPath("/v1#docs")).toBe("/v1#docs");
|
||||
expect(apiPath()).toBe("/v1");
|
||||
});
|
||||
|
||||
test("encodes tenant slugs as one path segment", () => {
|
||||
expect(appPath({ tenantSlug: " Acme Team/West ", path: "settings" })).toBe("/Acme%20Team%2FWest/settings");
|
||||
expect(() => appPath({ tenantSlug: " ", path: "settings" })).toThrow("tenantSlug is required");
|
||||
});
|
||||
|
||||
test("builds host-aware absolute URLs by default on the provided domain", () => {
|
||||
expect(appUrl({ rootDomain: "example.com", tenantSlug: "acme", path: "dashboard" })).toBe("https://example.com/acme/dashboard");
|
||||
expect(adminUrl({ rootDomain: "https://example.com", path: "/accounts/" })).toBe("https://example.com/accounts");
|
||||
expect(apiUrl({ rootDomain: "example.com", protocol: "http", path: "users" })).toBe("http://example.com/v1/users");
|
||||
});
|
||||
|
||||
test("builds host-aware absolute URLs with subdomain labels", () => {
|
||||
expect(appUrl({ rootDomain: "example.com", appSubdomain: "app", tenantSlug: "acme", path: "dashboard", mode: "host-aware" })).toBe(
|
||||
"https://app.example.com/acme/dashboard"
|
||||
);
|
||||
expect(adminUrl({ rootDomain: "example.com", adminSubdomain: "admin.", path: "accounts", mode: "host-aware" })).toBe("https://admin.example.com/accounts");
|
||||
expect(apiUrl({ rootDomain: "example.com", apiSubdomain: "api", path: "users", mode: "host-aware" })).toBe("https://api.example.com/v1/users");
|
||||
expect(apiUrl({ rootDomain: "example.com", apiSubdomain: " / ", path: "users", mode: "host-aware" })).toBe("https://example.com/v1/users");
|
||||
});
|
||||
|
||||
test("rejects blank absolute URL roots before building hosts", () => {
|
||||
expect(() => appUrl({ rootDomain: " ", tenantSlug: "acme", path: "dashboard" })).toThrow("rootDomain is required");
|
||||
});
|
||||
|
||||
test("builds host-aware absolute URLs with local ports and preserves query/hash suffixes", () => {
|
||||
expect(
|
||||
appUrl({
|
||||
rootDomain: "localhost:3000",
|
||||
protocol: "http",
|
||||
appSubdomain: "app",
|
||||
tenantSlug: "acme/team",
|
||||
path: "/settings/api/keys?tab=active#key",
|
||||
mode: "host-aware",
|
||||
})
|
||||
).toBe("http://app.localhost:3000/acme%2Fteam/settings/api/keys?tab=active#key");
|
||||
expect(
|
||||
adminUrl({
|
||||
rootDomain: "localhost:3000",
|
||||
protocol: "http",
|
||||
adminSubdomain: "admin",
|
||||
path: "/users?tab=active#u1",
|
||||
mode: "host-aware",
|
||||
})
|
||||
).toBe("http://admin.localhost:3000/users?tab=active#u1");
|
||||
expect(
|
||||
apiUrl({
|
||||
rootDomain: "localhost:3001",
|
||||
protocol: "http",
|
||||
apiSubdomain: "api",
|
||||
path: "/events?cursor=1#next",
|
||||
mode: "host-aware",
|
||||
})
|
||||
).toBe("http://api.localhost:3001/v1/events?cursor=1#next");
|
||||
});
|
||||
|
||||
test("does not rewrite removed app prefixes in path inputs", () => {
|
||||
expect(
|
||||
appUrl({
|
||||
rootDomain: "example.com",
|
||||
appSubdomain: "app",
|
||||
tenantSlug: "acme",
|
||||
path: "/app/acme/settings",
|
||||
mode: "host-aware",
|
||||
})
|
||||
).toBe("https://app.example.com/acme/app/acme/settings");
|
||||
});
|
||||
|
||||
test("supports default export helpers", () => {
|
||||
expect(CanonicalUrlUtils.apiPath("usage", { mode: "host-aware", version: "v1" })).toBe("/v1/usage");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,194 @@
|
||||
export type CanonicalUrlMode = "host-aware";
|
||||
export type ApiVersion = "v1";
|
||||
|
||||
export type PathInput = string | undefined;
|
||||
|
||||
export interface CanonicalPathOptions {
|
||||
mode?: CanonicalUrlMode;
|
||||
}
|
||||
|
||||
export interface AppPathOptions extends CanonicalPathOptions {
|
||||
tenantSlug: string;
|
||||
path?: PathInput;
|
||||
}
|
||||
|
||||
export interface AdminPathOptions extends CanonicalPathOptions {
|
||||
path?: PathInput;
|
||||
}
|
||||
|
||||
export interface ApiPathOptions extends CanonicalPathOptions {
|
||||
path?: PathInput;
|
||||
version?: ApiVersion;
|
||||
}
|
||||
|
||||
export interface AbsoluteUrlOptions extends CanonicalPathOptions {
|
||||
rootDomain: string;
|
||||
protocol?: "http" | "https";
|
||||
}
|
||||
|
||||
export interface AppUrlOptions extends AbsoluteUrlOptions {
|
||||
tenantSlug: string;
|
||||
path?: PathInput;
|
||||
appSubdomain?: string;
|
||||
}
|
||||
|
||||
export interface AdminUrlOptions extends AbsoluteUrlOptions {
|
||||
path?: PathInput;
|
||||
adminSubdomain?: string;
|
||||
}
|
||||
|
||||
export interface ApiUrlOptions extends AbsoluteUrlOptions {
|
||||
path?: PathInput;
|
||||
apiSubdomain?: string;
|
||||
version?: ApiVersion;
|
||||
}
|
||||
|
||||
const DEFAULT_PROTOCOL: AbsoluteUrlOptions["protocol"] = "https";
|
||||
const DEFAULT_API_VERSION: ApiVersion = "v1";
|
||||
|
||||
function encodeTenantSlug(tenantSlug: string) {
|
||||
const trimmed = tenantSlug.trim();
|
||||
if (!trimmed) {
|
||||
throw new Error("tenantSlug is required");
|
||||
}
|
||||
return encodeURIComponent(trimmed);
|
||||
}
|
||||
|
||||
function trimSlashes(value: string) {
|
||||
return value.replace(/^\/+|\/+$/g, "");
|
||||
}
|
||||
|
||||
function splitPathSuffix(path: string) {
|
||||
const queryIndex = path.indexOf("?");
|
||||
const hashIndex = path.indexOf("#");
|
||||
const indexes = [queryIndex, hashIndex].filter((index) => index >= 0);
|
||||
const suffixIndex = indexes.length > 0 ? Math.min(...indexes) : -1;
|
||||
|
||||
if (suffixIndex < 0) {
|
||||
return { pathname: path, suffix: "" };
|
||||
}
|
||||
|
||||
return {
|
||||
pathname: path.slice(0, suffixIndex),
|
||||
suffix: path.slice(suffixIndex),
|
||||
};
|
||||
}
|
||||
|
||||
function normalizeRelativePath(path: PathInput) {
|
||||
if (!path) {
|
||||
return "";
|
||||
}
|
||||
|
||||
const { pathname, suffix } = splitPathSuffix(path.trim());
|
||||
const normalizedPathname = trimSlashes(pathname).split("/").filter(Boolean).join("/");
|
||||
|
||||
return `${normalizedPathname}${suffix}`;
|
||||
}
|
||||
|
||||
function stripApiVersionPrefix(path: string) {
|
||||
const { pathname, suffix } = splitPathSuffix(path);
|
||||
const normalizedPathname = pathname.replace(/^api\/v1(?=\/|$)/, "").replace(/^v1(?=\/|$)/, "");
|
||||
return `${normalizedPathname}${suffix}`;
|
||||
}
|
||||
|
||||
function joinPath(...segments: Array<string | undefined>) {
|
||||
const nonEmptySegments = segments.filter((segment): segment is string => Boolean(segment));
|
||||
const lastSegment = nonEmptySegments.at(-1);
|
||||
let suffix = "";
|
||||
|
||||
if (lastSegment) {
|
||||
const split = splitPathSuffix(lastSegment);
|
||||
suffix = split.suffix;
|
||||
nonEmptySegments[nonEmptySegments.length - 1] = split.pathname;
|
||||
}
|
||||
|
||||
const joined = nonEmptySegments
|
||||
.map((segment) => trimSlashes(segment))
|
||||
.filter(Boolean)
|
||||
.join("/");
|
||||
|
||||
return `/${joined}${suffix}`;
|
||||
}
|
||||
|
||||
function normalizeHostLabel(label: string | undefined) {
|
||||
if (!label) {
|
||||
return undefined;
|
||||
}
|
||||
const normalized = trimSlashes(label.trim()).replace(/\.+$/g, "");
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function parseRootDomain(rootDomain: string, protocol: AbsoluteUrlOptions["protocol"] | undefined) {
|
||||
const trimmed = rootDomain.trim();
|
||||
if (!trimmed) {
|
||||
throw new Error("rootDomain is required");
|
||||
}
|
||||
|
||||
const withProtocol = /^[a-z][a-z\d+\-.]*:\/\//i.test(trimmed) ? trimmed : `${protocol ?? DEFAULT_PROTOCOL}://${trimmed}`;
|
||||
const url = new URL(withProtocol);
|
||||
|
||||
return {
|
||||
protocol: url.protocol.replace(":", ""),
|
||||
host: url.host.replace(/\/+$/g, ""),
|
||||
};
|
||||
}
|
||||
|
||||
function withSubdomain(host: string, subdomain: string | undefined) {
|
||||
const normalizedSubdomain = normalizeHostLabel(subdomain);
|
||||
if (!normalizedSubdomain) {
|
||||
return host;
|
||||
}
|
||||
|
||||
return `${normalizedSubdomain}.${host}`;
|
||||
}
|
||||
|
||||
function absoluteUrl(rootDomain: string, path: string, subdomain: string | undefined, protocol?: AbsoluteUrlOptions["protocol"]) {
|
||||
const root = parseRootDomain(rootDomain, protocol);
|
||||
return `${root.protocol}://${withSubdomain(root.host, subdomain)}${path}`;
|
||||
}
|
||||
|
||||
export function appPath({ tenantSlug, path }: AppPathOptions) {
|
||||
const normalizedPath = normalizeRelativePath(path);
|
||||
const tenantSegment = encodeTenantSlug(tenantSlug);
|
||||
|
||||
return joinPath(tenantSegment, normalizedPath);
|
||||
}
|
||||
|
||||
export function adminPath(pathOrOptions?: PathInput | AdminPathOptions, _options?: CanonicalPathOptions) {
|
||||
void _options;
|
||||
const path = typeof pathOrOptions === "object" && pathOrOptions !== null ? pathOrOptions.path : pathOrOptions;
|
||||
const normalizedPath = normalizeRelativePath(path);
|
||||
|
||||
return joinPath(normalizedPath);
|
||||
}
|
||||
|
||||
export function apiPath(pathOrOptions?: PathInput | ApiPathOptions, options?: ApiPathOptions) {
|
||||
const path = typeof pathOrOptions === "object" && pathOrOptions !== null ? pathOrOptions.path : pathOrOptions;
|
||||
const version = typeof pathOrOptions === "object" && pathOrOptions !== null ? pathOrOptions.version : options?.version;
|
||||
const normalizedPath = stripApiVersionPrefix(normalizeRelativePath(path));
|
||||
|
||||
return joinPath(version ?? DEFAULT_API_VERSION, normalizedPath);
|
||||
}
|
||||
|
||||
export function appUrl({ rootDomain, protocol, appSubdomain, ...pathOptions }: AppUrlOptions) {
|
||||
return absoluteUrl(rootDomain, appPath(pathOptions), appSubdomain, protocol);
|
||||
}
|
||||
|
||||
export function adminUrl({ rootDomain, protocol, adminSubdomain, path }: AdminUrlOptions) {
|
||||
return absoluteUrl(rootDomain, adminPath({ path }), adminSubdomain, protocol);
|
||||
}
|
||||
|
||||
export function apiUrl({ rootDomain, protocol, apiSubdomain, path, version }: ApiUrlOptions) {
|
||||
return absoluteUrl(rootDomain, apiPath({ path, version }), apiSubdomain, protocol);
|
||||
}
|
||||
|
||||
const canonicalUrlUtils = {
|
||||
appPath,
|
||||
adminPath,
|
||||
apiPath,
|
||||
appUrl,
|
||||
adminUrl,
|
||||
apiUrl,
|
||||
};
|
||||
|
||||
export default canonicalUrlUtils;
|
||||
@@ -0,0 +1,31 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import canonicalUrlUtils, {
|
||||
adminPath,
|
||||
adminUrl,
|
||||
apiPath,
|
||||
apiUrl,
|
||||
appPath,
|
||||
appUrl,
|
||||
} from "./canonical.js";
|
||||
|
||||
import type { AppPathOptions, CanonicalUrlMode } from "./canonical.js";
|
||||
|
||||
describe("@toolctrl/url canonical exports", () => {
|
||||
it("exports canonical helpers and the default helper object", () => {
|
||||
expect(appPath({ tenantSlug: "acme" })).toBe("/acme");
|
||||
expect(adminPath("users")).toBe("/users");
|
||||
expect(apiPath("health")).toBe("/v1/health");
|
||||
expect(appUrl({ rootDomain: "example.com", tenantSlug: "acme" })).toBe("https://example.com/acme");
|
||||
expect(adminUrl({ rootDomain: "example.com", path: "users" })).toBe("https://example.com/users");
|
||||
expect(apiUrl({ rootDomain: "example.com", path: "health" })).toBe("https://example.com/v1/health");
|
||||
expect(canonicalUrlUtils).toMatchObject({ appPath, adminPath, apiPath, appUrl, adminUrl, apiUrl });
|
||||
});
|
||||
|
||||
it("keeps public types importable", () => {
|
||||
const mode: CanonicalUrlMode = "host-aware";
|
||||
const options: AppPathOptions = { tenantSlug: "acme", mode };
|
||||
|
||||
expect(appPath(options)).toBe("/acme");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,23 @@
|
||||
export {
|
||||
adminPath,
|
||||
adminUrl,
|
||||
apiPath,
|
||||
apiUrl,
|
||||
appPath,
|
||||
appUrl,
|
||||
default,
|
||||
} from "./canonical.js";
|
||||
|
||||
export type {
|
||||
AbsoluteUrlOptions,
|
||||
AdminPathOptions,
|
||||
AdminUrlOptions,
|
||||
ApiPathOptions,
|
||||
ApiUrlOptions,
|
||||
ApiVersion,
|
||||
AppPathOptions,
|
||||
AppUrlOptions,
|
||||
CanonicalPathOptions,
|
||||
CanonicalUrlMode,
|
||||
PathInput,
|
||||
} from "./canonical.js";
|
||||
Reference in new issue
Block a user