conform casing and documentation

frontend/lib/api/base/index.test.ts

@@ -1,24 +1,24 @@
 import { describe, expect, it } from 'vitest';
-import { UrlBuilder } from '.';
+import { route } from '.';
 
 describe('UrlBuilder', () => {
-	it('basic query parameter', () => {
-		const result = UrlBuilder('/test', { a: 'b' });
-		expect(result).toBe('/api/v1/test?a=b');
-	});
+  it('basic query parameter', () => {
+    const result = route('/test', { a: 'b' });
+    expect(result).toBe('/api/v1/test?a=b');
+  });
 
-	it('multiple query parameters', () => {
-		const result = UrlBuilder('/test', { a: 'b', c: 'd' });
-		expect(result).toBe('/api/v1/test?a=b&c=d');
-	});
+  it('multiple query parameters', () => {
+    const result = route('/test', { a: 'b', c: 'd' });
+    expect(result).toBe('/api/v1/test?a=b&c=d');
+  });
 
-	it('no query parameters', () => {
-		const result = UrlBuilder('/test');
-		expect(result).toBe('/api/v1/test');
-	});
+  it('no query parameters', () => {
+    const result = route('/test');
+    expect(result).toBe('/api/v1/test');
+  });
 
-	it('list-like query parameters', () => {
-		const result = UrlBuilder('/test', { a: ['b', 'c'] });
-		expect(result).toBe('/api/v1/test?a=b&a=c');
-	});
+  it('list-like query parameters', () => {
+    const result = route('/test', { a: ['b', 'c'] });
+    expect(result).toBe('/api/v1/test?a=b&a=c');
+  });
 });

frontend/lib/api/base/index.ts

@@ -1,2 +1,2 @@
 export { BaseAPI } from './base-api';
-export { UrlBuilder } from './urls';
+export { route } from './urls';

frontend/lib/api/base/urls.ts

@@ -3,14 +3,23 @@ const parts = {
   prefix: '/api/v1',
 };
 
-export function OverrideParts(host: string, prefix: string) {
+export function overrideParts(host: string, prefix: string) {
   parts.host = host;
   parts.prefix = prefix;
 }
 
 export type QueryValue = string | string[] | number | number[] | boolean | null | undefined;
 
-export function UrlBuilder(rest: string, params: Record<string, QueryValue> = {}): string {
+/**
+ * route is a the main URL builder for the API. It will use a predefined host and prefix (global)
+ * in the urls.ts file and then append the passed in path parameter uring the `URL` class from the
+ * browser. It will also append any query parameters passed in as the second parameter.
+ *
+ * The default host `http://localhost.com` is removed from the path if it is present. This allows us
+ * to bootstrap the API with different hosts as needed (like for testing) but still allows us to use
+ * relative URLs in pruduction because the API and client bundle are served from the same server/host.
+ */
+export function route(rest: string, params: Record<string, QueryValue> = {}): string {
   const url = new URL(parts.prefix + rest, parts.host);
 
   for (const [key, value] of Object.entries(params)) {
@@ -23,6 +32,5 @@ export function UrlBuilder(rest: string, params: Record<string, QueryValue> = {}
     }
   }
 
-  // we return the path only, without the base URL
   return url.toString().replace('http://localhost.com', '');
 }