@platformos/platformos-common 0.0.11 → 0.0.12

package/src/route-table/parseSlug.ts

@@ -0,0 +1,136 @@
+import { RouteSegment } from './types';
+
+/**
+ * Parse a single segment string (without slashes) into a RouteSegment.
+ * - Starts with `:` -> param
+ * - Starts with `*` -> wildcard
+ * - Otherwise -> static
+ */
+function parseSegment(raw: string): RouteSegment {
+  // Strip trailing `)` if present (from optional group splitting)
+  const cleaned = raw.endsWith(')') ? raw.slice(0, -1) : raw;
+
+  if (cleaned.startsWith(':')) {
+    return { type: 'param', name: cleaned.slice(1) };
+  }
+  if (cleaned.startsWith('*')) {
+    return { type: 'wildcard', name: cleaned.slice(1) || '*' };
+  }
+  return { type: 'static', value: cleaned };
+}
+
+function parseSegments(part: string): RouteSegment[] {
+  return part
+    .split('/')
+    .filter((s) => s.length > 0)
+    .map(parseSegment);
+}
+
+export interface ParsedSlug {
+  requiredSegments: RouteSegment[];
+  optionalGroups: RouteSegment[][];
+}
+
+/**
+ * Parse a slug string into required segments and optional groups.
+ *
+ * Slug syntax:
+ *   - `about` -> required: [static('about')]
+ *   - `users/:id` -> required: [static('users'), param('id')]
+ *   - `users(/:id)` -> required: [static('users')], optional: [[param('id')]]
+ *   - `search(/:country)(/:city)` -> required: [static('search')], optional: [[param('country')], [param('city')]]
+ *   - `users(/section/*)` -> required: [static('users')], optional: [[static('section'), wildcard('*')]]
+ *   - `/` (root) -> required: [], optional: []
+ */
+export function parseSlug(slug: string): ParsedSlug {
+  // Root is special
+  if (slug === '/' || slug === '') {
+    return { requiredSegments: [], optionalGroups: [] };
+  }
+
+  // Split into required part and optional groups by finding `(`
+  const firstParen = slug.indexOf('(');
+
+  if (firstParen === -1) {
+    // No optional groups
+    return {
+      requiredSegments: parseSegments(slug),
+      optionalGroups: [],
+    };
+  }
+
+  // Required part is everything before the first `(`
+  const requiredPart = slug.slice(0, firstParen);
+  const optionalPart = slug.slice(firstParen);
+
+  const requiredSegments = requiredPart.length > 0 ? parseSegments(requiredPart) : [];
+
+  // Parse optional groups: split on `(` to get each group, strip `)` and leading `/`
+  const optionalGroups: RouteSegment[][] = [];
+  const groupRegex = /\(([^)]+)\)/g;
+  let match: RegExpExecArray | null;
+  while ((match = groupRegex.exec(optionalPart)) !== null) {
+    const groupContent = match[1];
+    // Strip leading `/` if present
+    const normalized = groupContent.startsWith('/') ? groupContent.slice(1) : groupContent;
+    if (normalized.length > 0) {
+      optionalGroups.push(parseSegments(normalized));
+    }
+  }
+
+  return { requiredSegments, optionalGroups };
+}
+
+/**
+ * Calculate route precedence following the backend's scoring algorithm.
+ * Returns a negative number; more negative = higher priority.
+ * When sorting ascending, highest-priority routes come first.
+ *
+ * Segment weights:
+ * - Static/hardcoded: 100 points
+ * - Required parameter (:param): 10 points
+ * - Optional parameter (inside parens): 1 point
+ *
+ * Base: weighted_size * -100
+ * Adjustments: slug='/' +1, format='html' +1, format-in-last-component -1
+ */
+export function calculatePrecedence(slug: string, format: string): number {
+  if (slug === '/' || slug === '') {
+    // Special case for root: weighted_size=0 -> use 1
+    let precedence = 1 * -100;
+    precedence += 1; // root "/" adjustment
+    if (format === 'html') precedence += 1;
+    return precedence;
+  }
+
+  // Split on `(?/` boundary to get all segments with their weight context
+  // The Ruby code: slug.split(%r{\(?/}).inject(0) { ... }
+  const parts = slug.split(/\(?\//);
+  let weightedSize = 0;
+  for (const part of parts) {
+    if (part.length === 0) continue;
+    if (part.startsWith(':')) {
+      weightedSize += part.endsWith(')') ? 1 : 10;
+    } else if (part.startsWith('*')) {
+      weightedSize += part.endsWith(')') ? 1 : 10;
+    } else {
+      weightedSize += 100;
+    }
+  }
+
+  let precedence = (weightedSize === 0 ? 1 : weightedSize) * -100;
+
+  if (format === 'html') precedence += 1;
+
+  // Check if format is embedded in last slug component (e.g. `data.json`)
+  const lastSlash = slug.lastIndexOf('/');
+  const lastComponent = lastSlash >= 0 ? slug.slice(lastSlash + 1) : slug;
+  // Strip optional group parens for checking
+  const cleanLast = lastComponent.replace(/[()]/g, '');
+  const dotIdx = cleanLast.lastIndexOf('.');
+  if (dotIdx > 0 && dotIdx < cleanLast.length - 1) {
+    precedence -= 1;
+  }
+
+  return precedence;
+}

package/src/route-table/slugFromFilePath.spec.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { slugFromFilePath, formatFromFilePath } from './slugFromFilePath';
+
+describe('slugFromFilePath', () => {
+  it('derives / from index.html.liquid', () => {
+    expect(slugFromFilePath('index.html.liquid', 'html')).toBe('/');
+  });
+
+  it('derives / from index.liquid', () => {
+    expect(slugFromFilePath('index.liquid', 'html')).toBe('/');
+  });
+
+  it('derives / from home.html.liquid (deprecated alias)', () => {
+    expect(slugFromFilePath('home.html.liquid', 'html')).toBe('/');
+  });
+
+  it('derives / from home.liquid (deprecated alias)', () => {
+    expect(slugFromFilePath('home.liquid', 'html')).toBe('/');
+  });
+
+  it('derives about from about.html.liquid', () => {
+    expect(slugFromFilePath('about.html.liquid', 'html')).toBe('about');
+  });
+
+  it('derives about from about.liquid', () => {
+    expect(slugFromFilePath('about.liquid', 'html')).toBe('about');
+  });
+
+  it('derives users/show from users/show.html.liquid', () => {
+    expect(slugFromFilePath('users/show.html.liquid', 'html')).toBe('users/show');
+  });
+
+  it('derives users from users/index.html.liquid', () => {
+    expect(slugFromFilePath('users/index.html.liquid', 'html')).toBe('users');
+  });
+
+  it('derives users from users/index.liquid', () => {
+    expect(slugFromFilePath('users/index.liquid', 'html')).toBe('users');
+  });
+
+  it('derives api/v2/data from api/v2/data.json.liquid', () => {
+    expect(slugFromFilePath('api/v2/data.json.liquid', 'json')).toBe('api/v2/data');
+  });
+
+  it('derives api/v2/data from api/v2/data.liquid', () => {
+    expect(slugFromFilePath('api/v2/data.liquid', 'html')).toBe('api/v2/data');
+  });
+
+  it('derives deeply/nested/path/page from deeply/nested/path/page.html.liquid', () => {
+    expect(slugFromFilePath('deeply/nested/path/page.html.liquid', 'html')).toBe(
+      'deeply/nested/path/page',
+    );
+  });
+
+  it('derives test/abc from test/abc/index.html.liquid', () => {
+    expect(slugFromFilePath('test/abc/index.html.liquid', 'html')).toBe('test/abc');
+  });
+});
+
+describe('formatFromFilePath', () => {
+  it('returns html for plain .liquid files', () => {
+    expect(formatFromFilePath('about.liquid')).toBe('html');
+  });
+
+  it('returns html for .html.liquid files', () => {
+    expect(formatFromFilePath('about.html.liquid')).toBe('html');
+  });
+
+  it('returns json for .json.liquid files', () => {
+    expect(formatFromFilePath('api/data.json.liquid')).toBe('json');
+  });
+
+  it('returns xml for .xml.liquid files', () => {
+    expect(formatFromFilePath('feed.xml.liquid')).toBe('xml');
+  });
+
+  it('returns csv for .csv.liquid files', () => {
+    expect(formatFromFilePath('export.csv.liquid')).toBe('csv');
+  });
+
+  it('returns html for index.liquid', () => {
+    expect(formatFromFilePath('index.liquid')).toBe('html');
+  });
+});

package/src/route-table/slugFromFilePath.ts

@@ -0,0 +1,84 @@
+/**
+ * Derives a URL slug from a page file path relative to the pages directory.
+ *
+ * Rules (ported from Ruby Page.default_routing_options):
+ * 1. Strip file extensions: first `.liquid`, then `.{format}` (e.g. `.html`)
+ * 2. If result is `index` -> slug = `/`
+ * 3. If result ends with `/index` -> strip it (e.g. `test/index` -> `test`)
+ * 4. If result is `home` -> slug = `/` (deprecated alias for root)
+ * 5. Otherwise slug = the remaining path
+ */
+export function slugFromFilePath(relativeToPages: string, format: string = 'html'): string {
+  // Strip .liquid extension first
+  let slug = relativeToPages;
+  if (slug.endsWith('.liquid')) {
+    slug = slug.slice(0, -'.liquid'.length);
+  }
+
+  // Strip .{format} extension (e.g. .html, .json)
+  if (slug.endsWith(`.${format}`)) {
+    slug = slug.slice(0, -`.${format}`.length);
+  }
+
+  // index -> root
+  if (slug === 'index') {
+    return '/';
+  }
+
+  // path/to/index -> path/to
+  if (slug.endsWith('/index')) {
+    return slug.slice(0, -'/index'.length);
+  }
+
+  // home -> root (deprecated alias)
+  if (slug === 'home') {
+    return '/';
+  }
+
+  return slug;
+}
+
+/**
+ * Known response formats supported by the platformOS engine.
+ * Derived from the platform's FORMAT_ENUM.
+ */
+export const KNOWN_FORMATS = new Set([
+  'html',
+  'json',
+  'xml',
+  'rss',
+  'csv',
+  'pdf',
+  'css',
+  'text',
+  'js',
+  'txt',
+  'svg',
+  'ics',
+]);
+
+/**
+ * Extracts the format from a page filename.
+ * Returns the format if the file has a double extension like `.json.liquid` or `.xml.liquid`
+ * and the extension is a known platformOS format.
+ * Returns 'html' as the default if only `.liquid` is present or the extension is unknown.
+ */
+export function formatFromFilePath(relativeToPages: string): string {
+  // Strip .liquid first
+  let name = relativeToPages;
+  if (name.endsWith('.liquid')) {
+    name = name.slice(0, -'.liquid'.length);
+  }
+
+  // Check for a remaining extension
+  const lastDot = name.lastIndexOf('.');
+  const lastSlash = name.lastIndexOf('/');
+  if (lastDot > lastSlash && lastDot > 0) {
+    const ext = name.slice(lastDot + 1);
+    if (KNOWN_FORMATS.has(ext)) {
+      return ext;
+    }
+  }
+
+  return 'html';
+}

package/src/route-table/types.ts

@@ -0,0 +1,25 @@
+export type RouteSegment =
+  | { type: 'static'; value: string }
+  | { type: 'param'; name: string }
+  | { type: 'wildcard'; name: string };
+
+export interface RouteEntry {
+  /** The resolved slug, e.g. "users/:id" or "/" */
+  slug: string;
+  /** HTTP method: get, post, put, patch, delete. Default: "get" */
+  method: string;
+  /** Response format: html, json, xml, etc. Default: "html" */
+  format: string;
+  /** URI of the source .liquid file */
+  uri: string;
+  /** Parsed required segments */
+  requiredSegments: RouteSegment[];
+  /** Parsed optional segment groups (each group is a sequence of segments) */
+  optionalGroups: RouteSegment[][];
+  /**
+   * Computed precedence score. More negative = higher priority.
+   * Scores are negative (e.g. -10000 for a route with many static segments).
+   * When sorting, ascending order puts highest-priority routes first.
+   */
+  precedence: number;
+}

package/src/translation-provider/TranslationProvider.ts

@@ -52,7 +52,7 @@ export class TranslationProvider {
     return key ? { isModule: true, moduleName, key } : { isModule: false, key: translationKey };
   }
 
-  private getSearchPaths(moduleName?: string): string[] {
+  static getSearchPaths(moduleName?: string): string[] {
     if (!moduleName) {
       return ['app/translations'];
     }
@@ -76,7 +76,9 @@ export class TranslationProvider {
       return [undefined, undefined];
     }
 
-    const searchPaths = this.getSearchPaths(parsed.isModule ? parsed.moduleName : undefined);
+    const searchPaths = TranslationProvider.getSearchPaths(
+      parsed.isModule ? parsed.moduleName : undefined,
+    );
 
     for (const basePath of searchPaths) {
       // Strategy A: single locale file ({basePath}/{locale}.yml)