@mzebley/mark-down 1.0.0 → 1.1.0

package/src/snippet-client.ts

@@ -1,215 +1,412 @@
-import matter from "gray-matter";
-import { marked } from "marked";
+import { normalizeSlug } from "./slug";
+import { parseFrontMatter } from "./front-matter";
+import { renderMarkdown } from "./markdown";
+import { ManifestLoadError, SnippetNotFoundError } from "./errors";
 import type {
-  ListOptions,
   ManifestSource,
   ResponseLike,
   Snippet,
   SnippetClientOptions,
-  SnippetFilter,
-  SnippetMeta
+  SnippetFetcherResult,
+  SnippetMeta,
+  SnippetSearchFilter
 } from "./types";
 
-const OPTIONAL_FIELDS: Array<keyof SnippetMeta> = [
-  "title",
-  "order",
-  "type",
-  "tags",
-  "draft"
-];
+export { ManifestLoadError, SnippetNotFoundError } from "./errors";
+
+interface SnippetClientInternalOptions {
+  manifest: ManifestSource;
+  base?: string;
+  fetch: (url: string) => Promise<string>;
+  frontMatter: boolean;
+  cache: boolean;
+  verbose: boolean;
+  render: (markdown: string) => Promise<string>;
+}
+
+const HTTP_PATTERN = /^https?:\/\//i;
 
 export class SnippetClient {
-  private readonly manifestSource: ManifestSource;
-  private readonly fetcher: (input: string) => Promise<ResponseLike>;
-  private readonly markdownRenderer: (markdown: string) => Promise<string> | string;
-  private readonly resolveSnippetPath: (meta: SnippetMeta) => string;
+  private readonly options: SnippetClientInternalOptions;
+  private readonly manifestUrl?: string;
+  private readonly inferredBase?: string;
+
   private manifestPromise?: Promise<SnippetMeta[]>;
-  private snippetCache = new Map<string, Promise<Snippet>>();
+  private readonly snippetCache = new Map<string, Promise<Snippet>>();
 
   constructor(options: SnippetClientOptions) {
-    this.manifestSource = options.manifest;
-    this.fetcher = options.fetcher ?? defaultFetch;
-    this.markdownRenderer = options.markdownRenderer ?? marked.parse;
-    this.resolveSnippetPath = options.resolveSnippetPath ?? ((meta) => meta.path);
+    if (!options || !options.manifest) {
+      throw new ManifestLoadError("A manifest source must be provided to SnippetClient.");
+    }
+
+    this.manifestUrl = typeof options.manifest === "string" ? options.manifest : undefined;
+    this.inferredBase = this.manifestUrl ? deriveBaseFromManifest(this.manifestUrl) : undefined;
+
+    const fetcher = options.fetch ?? defaultFetch;
+
+    const renderOption = options.render;
+
+    const renderer = renderOption
+      ? async (markdown: string) => Promise.resolve(renderOption(markdown))
+      : async (markdown: string) => Promise.resolve(renderMarkdown(markdown));
+
+    this.options = {
+      manifest: options.manifest,
+      base: options.base,
+      fetch: async (url: string) => {
+        const response = await fetcher(url);
+        if (typeof response === "string") {
+          return response;
+        }
+        return resolveResponseText(response, url);
+      },
+      frontMatter: options.frontMatter !== false,
+      cache: options.cache !== false,
+      verbose: options.verbose === true,
+      render: renderer
+    };
   }
 
-  async get(slug: string): Promise<Snippet | undefined> {
+  async get(slug: string): Promise<Snippet> {
     const manifest = await this.loadManifest();
-    const entry = manifest.find((snippet) => snippet.slug === slug);
+    const entry = manifest.find((item) => item.slug === slug);
     if (!entry) {
-      return undefined;
+      throw new SnippetNotFoundError(slug);
     }
-
     return this.loadSnippet(entry);
   }
 
-  async list(filter?: SnippetFilter | ListOptions, options?: ListOptions): Promise<SnippetMeta[]> {
+  async listAll(): Promise<SnippetMeta[]> {
     const manifest = await this.loadManifest();
-    let predicate: SnippetFilter | undefined;
-    let finalOptions: ListOptions = {};
-
-    if (typeof filter === "function") {
-      predicate = filter;
-      finalOptions = options ?? {};
-    } else if (filter) {
-      finalOptions = filter;
-    } else if (options) {
-      finalOptions = options;
-    }
+    return manifest.map(cloneMeta);
+  }
 
-    let items = manifest;
-    const filters: SnippetFilter[] = [];
-    if (predicate) {
-      filters.push(predicate);
-    }
-    if (finalOptions.filter) {
-      filters.push(finalOptions.filter);
-    }
-    if (filters.length) {
-      items = items.filter((entry) => filters.every((fn) => fn(entry)));
-    }
+  async listByGroup(group: string): Promise<SnippetMeta[]> {
+    const manifest = await this.loadManifest();
+    return manifest
+      .filter((item) => (item.group ?? null) === group)
+      .map(cloneMeta);
+  }
 
-    const offset = finalOptions.offset ?? 0;
-    const limit = finalOptions.limit;
-    if (offset > 0) {
-      items = items.slice(offset);
-    }
-    if (typeof limit === "number") {
-      items = items.slice(0, limit);
-    }
+  async listByType(type: string): Promise<SnippetMeta[]> {
+    const manifest = await this.loadManifest();
+    return manifest
+      .filter((item) => item.type === type)
+      .map(cloneMeta);
+  }
 
-    return [...items];
+  async search(filter: SnippetSearchFilter): Promise<SnippetMeta[]> {
+    const manifest = await this.loadManifest();
+    const tags = filter.tags ?? [];
+    const mode = filter.tagsMode ?? "any";
+
+    return manifest
+      .filter((item) => {
+        if (filter.type && item.type !== filter.type) {
+          return false;
+        }
+        if (filter.group && (item.group ?? undefined) !== filter.group) {
+          return false;
+        }
+        if (!tags.length) {
+          return true;
+        }
+        const metaTags = item.tags ?? [];
+        if (!metaTags.length) {
+          return false;
+        }
+        if (mode === "all") {
+          return tags.every((tag) => metaTags.includes(tag));
+        }
+        return tags.some((tag) => metaTags.includes(tag));
+      })
+      .map(cloneMeta);
+  }
+
+  async getHtml(slug: string): Promise<string> {
+    const snippet = await this.get(slug);
+    return snippet.html;
+  }
+
+  invalidate(): void {
+    this.manifestPromise = undefined;
+    this.snippetCache.clear();
   }
 
-  listByType(type: string, options?: ListOptions): Promise<SnippetMeta[]> {
-    return this.list((entry) => entry.type === type, options);
+  invalidateSlug(slug: string): void {
+    this.snippetCache.delete(slug);
+  }
+
+  private async loadManifest(): Promise<SnippetMeta[]> {
+    if (this.options.cache && this.manifestPromise) {
+      return this.manifestPromise;
+    }
+
+    const promise = this.resolveManifest();
+    if (this.options.cache) {
+      this.manifestPromise = promise;
+    }
+    return promise;
   }
 
-  listByGroup(group: string, options?: ListOptions): Promise<SnippetMeta[]> {
-    return this.list((entry) => entry.group === group, options);
+  private async resolveManifest(): Promise<SnippetMeta[]> {
+    const source = this.options.manifest;
+    let entries: SnippetMeta[];
+
+    try {
+      if (Array.isArray(source)) {
+        entries = source.map(normalizeManifestEntry);
+      } else if (typeof source === "function") {
+        const result = await source();
+        if (!Array.isArray(result)) {
+          throw new ManifestLoadError("Manifest loader must resolve to an array of snippet metadata.");
+        }
+        entries = result.map(normalizeManifestEntry);
+      } else {
+        const raw = await this.options.fetch(source);
+        entries = parseManifest(raw, source).map(normalizeManifestEntry);
+      }
+    } catch (error) {
+      if (error instanceof ManifestLoadError) {
+        throw error;
+      }
+      throw new ManifestLoadError("Failed to load snippet manifest.", error);
+    }
+
+    return entries.map(cloneMeta);
   }
 
   private loadSnippet(meta: SnippetMeta): Promise<Snippet> {
-    const cached = this.snippetCache.get(meta.slug);
+    const cached = this.options.cache ? this.snippetCache.get(meta.slug) : undefined;
     if (cached) {
       return cached;
     }
-
     const promise = this.fetchSnippet(meta);
-    this.snippetCache.set(meta.slug, promise);
+    if (this.options.cache) {
+      this.snippetCache.set(meta.slug, promise);
+    }
     return promise;
   }
 
   private async fetchSnippet(meta: SnippetMeta): Promise<Snippet> {
-    const snippetPath = this.resolveSnippetPath(meta);
-    const response = await this.fetcher(snippetPath);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch snippet '${meta.slug}' (status ${response.status})`);
+    const url = this.resolveSnippetPath(meta.path);
+    let raw: string;
+    try {
+      raw = await this.options.fetch(url);
+    } catch (error) {
+      throw new ManifestLoadError(`Failed to fetch snippet at '${url}'.`, error);
     }
 
-    const rawContent = await response.text();
-    const parsed = matter(rawContent);
-    const frontMatter = sanitizeFrontMatter(parsed.data ?? {});
-    const mergedMeta = mergeFrontMatter(meta, frontMatter.meta);
+    const frontMatter = this.options.frontMatter ? parseFrontMatter(raw) : undefined;
+    const body = frontMatter?.content ?? raw;
+    const html = await this.options.render(body);
 
-    const html = await this.markdownRenderer(parsed.content);
-
-    const baseExtra = mergedMeta.extra ?? {};
-    return {
-      ...mergedMeta,
-      extra: {
-        ...baseExtra,
-        ...frontMatter.extra
-      },
-      markdown: parsed.content,
-      html
+    const merged: SnippetMeta = {
+      ...meta,
+      ...pickMeta(frontMatter?.meta),
+      extra: mergeExtra(meta.extra, frontMatter?.extra)
     };
-  }
 
-  private loadManifest(): Promise<SnippetMeta[]> {
-    if (!this.manifestPromise) {
-      this.manifestPromise = this.resolveManifest();
+    if (frontMatter?.slug) {
+      try {
+        const normalizedFrontSlug = normalizeSlug(frontMatter.slug);
+        if (normalizedFrontSlug !== meta.slug && this.options.verbose) {
+          console.warn(
+            `Front-matter slug '${frontMatter.slug}' (normalized: '${normalizedFrontSlug}') differs from manifest slug '${meta.slug}'.`
+          );
+        }
+      } catch (error) {
+        if (this.options.verbose) {
+          console.warn(`Failed to normalize front-matter slug '${frontMatter.slug}':`, error);
+        }
+      }
+    }
+
+    const snippet: Snippet = { ...merged, html, raw: body, markdown: body };
+    if (merged.tags) {
+      snippet.tags = [...merged.tags];
     }
-    return this.manifestPromise;
+    return snippet;
   }
 
-  private async resolveManifest(): Promise<SnippetMeta[]> {
-    if (Array.isArray(this.manifestSource)) {
-      return this.manifestSource;
+  private resolveSnippetPath(path: string): string {
+    if (HTTP_PATTERN.test(path)) {
+      return normalizeForwardSlashes(path);
     }
 
-    if (typeof this.manifestSource === "function") {
-      const result = await this.manifestSource();
-      return Array.isArray(result) ? result : Promise.reject(new Error("Manifest function must return an array"));
+    const base = this.options.base ?? this.inferredBase ?? "";
+
+    if (path.startsWith("/")) {
+      if (base) {
+        return joinPaths(base, path);
+      }
+      return normalizeForwardSlashes(path);
     }
 
-    const raw = await this.fetchText(this.manifestSource);
-    const manifest = JSON.parse(raw);
-    if (!Array.isArray(manifest)) {
-      throw new Error("Manifest must be an array");
+    if (base) {
+      return joinPaths(base, path);
     }
-    return manifest;
+    return normalizeForwardSlashes(path);
   }
+}
 
-  private async fetchText(path: string): Promise<string> {
-    const response = await this.fetcher(path);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch manifest from ${path} (status ${response.status})`);
-    }
-    return response.text();
+function parseManifest(raw: string, source: string): SnippetMeta[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ManifestLoadError(`Manifest at '${source}' is not valid JSON.`, error);
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new ManifestLoadError(`Manifest at '${source}' must be a JSON array.`);
   }
+
+  return parsed as SnippetMeta[];
 }
 
-function sanitizeFrontMatter(data: Record<string, unknown>) {
-  const meta: Partial<SnippetMeta> = {};
-  const extra: Record<string, unknown> = {};
+function normalizeManifestEntry(entry: SnippetMeta): SnippetMeta {
+  if (!entry.slug) {
+    throw new ManifestLoadError("Manifest entry is missing required 'slug' property.");
+  }
+  if (!entry.path) {
+    throw new ManifestLoadError(`Manifest entry for '${entry.slug}' is missing required 'path'.`);
+  }
+  const normalized: SnippetMeta = {
+    slug: entry.slug,
+    title: entry.title,
+    type: entry.type,
+    order: entry.order,
+    tags: entry.tags ? [...entry.tags] : undefined,
+    path: normalizeForwardSlashes(entry.path),
+    group: entry.group ?? null,
+    draft: entry.draft,
+    extra: cloneRecord(entry.extra)
+  };
+  return normalized;
+}
 
-  for (const [key, value] of Object.entries(data)) {
-    if (OPTIONAL_FIELDS.includes(key as keyof SnippetMeta)) {
-      if (key === "tags") {
-        meta.tags = normalizeTags(value);
-      } else {
-        (meta as Record<string, unknown>)[key] = value;
-      }
-    } else {
-      extra[key] = value;
+function deriveBaseFromManifest(manifest: string): string | undefined {
+  if (HTTP_PATTERN.test(manifest)) {
+    try {
+      const url = new URL(manifest);
+      url.hash = "";
+      url.search = "";
+      const path = url.pathname;
+      url.pathname = path.replace(/[^/]*$/, "");
+      return url.toString();
+    } catch (error) {
+      console.warn(`Unable to derive base from manifest '${manifest}':`, error);
+      return undefined;
     }
   }
 
-  return { meta, extra };
+  const sanitized = manifest.replace(/[?#].*$/, "");
+  const index = sanitized.lastIndexOf("/");
+  if (index === -1) {
+    return undefined;
+  }
+  return sanitized.slice(0, index + 1);
 }
 
-function normalizeTags(value: unknown): string[] | undefined {
-  if (!value) {
-    return undefined;
+function joinPaths(base: string, relative: string): string {
+  if (HTTP_PATTERN.test(base)) {
+    return new URL(relative, base).toString();
   }
-  if (Array.isArray(value)) {
-    return value.map((tag) => String(tag));
+  const leading = base.endsWith("/") ? base : `${base}/`;
+  const trimmed = relative.startsWith("/") ? relative.slice(1) : relative;
+  return normalizeForwardSlashes(`${leading}${trimmed}`);
+}
+
+function normalizeForwardSlashes(value: string): string {
+  if (HTTP_PATTERN.test(value)) {
+    try {
+      const url = new URL(value);
+      url.pathname = url.pathname.replace(/\/{2,}/g, "/");
+      return url.toString();
+    } catch {
+      // fall back to manual normalization below
+    }
   }
-  if (typeof value === "string") {
-    return value
-      .split(",")
-      .map((tag) => tag.trim())
-      .filter(Boolean);
+
+  if (value.startsWith("//")) {
+    return `//${value.slice(2).replace(/\/{2,}/g, "/")}`;
   }
-  return undefined;
+
+  if (value.startsWith("/")) {
+    return `/${value
+      .slice(1)
+      .replace(/\/{2,}/g, "/")}`;
+  }
+
+  return value.replace(/\/{2,}/g, "/");
 }
 
-function mergeFrontMatter(base: SnippetMeta, overrides: Partial<SnippetMeta>): SnippetMeta {
-  const merged: SnippetMeta = { ...base };
-  for (const field of OPTIONAL_FIELDS) {
-    const overrideValue = overrides[field];
-    if (overrideValue !== undefined && merged[field] === undefined) {
-      merged[field] = overrideValue as never;
-    }
+function mergeExtra(
+  base: Record<string, unknown> | undefined,
+  overrides: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!base && !overrides) {
+    return undefined;
+  }
+  return { ...(base ?? {}), ...(overrides ?? {}) };
+}
+
+function cloneRecord<T extends Record<string, unknown> | undefined>(value: T): T {
+  if (!value) {
+    return value;
   }
-  return merged;
+  return { ...value } as T;
 }
 
-async function defaultFetch(input: string): Promise<ResponseLike> {
+function cloneMeta(meta: SnippetMeta): SnippetMeta {
+  return {
+    ...meta,
+    tags: meta.tags ? [...meta.tags] : undefined,
+    extra: cloneRecord(meta.extra)
+  };
+}
+
+async function defaultFetch(url: string): Promise<SnippetFetcherResult> {
   const runtimeFetch = (globalThis as typeof globalThis & { fetch?: typeof fetch }).fetch;
   if (!runtimeFetch) {
-    throw new Error("No global fetch implementation found. Provide a custom fetcher.");
+    throw new ManifestLoadError("No global fetch implementation is available. Provide a custom fetch function.");
+  }
+  return runtimeFetch(url);
+}
+
+async function resolveResponseText(response: ResponseLike, url: string): Promise<string> {
+  if (!response.ok) {
+    throw new ManifestLoadError(`Request to '${url}' failed with status ${response.status}.`);
+  }
+  return response.text();
+}
+
+function pickMeta(meta?: Partial<SnippetMeta>): Partial<SnippetMeta> {
+  if (!meta) {
+    return {};
+  }
+  const result: Partial<SnippetMeta> = {};
+  if (meta.title !== undefined) {
+    result.title = meta.title;
+  }
+  if (meta.type !== undefined) {
+    result.type = meta.type;
+  }
+  if (meta.order !== undefined) {
+    result.order = meta.order;
+  }
+  if (meta.tags !== undefined) {
+    result.tags = [...meta.tags];
+  }
+  if (meta.group !== undefined) {
+    result.group = meta.group;
+  }
+  if (meta.draft !== undefined) {
+    result.draft = meta.draft;
+  }
+  if (meta.path !== undefined) {
+    result.path = meta.path;
   }
-  return runtimeFetch(input);
+  return result;
 }

package/src/types.ts

@@ -1,26 +1,26 @@
 export interface SnippetMeta {
   slug: string;
   title?: string;
-  order?: number | null;
   type?: string;
+  order?: number;
   tags?: string[];
-  draft?: boolean;
   path: string;
-  group: string;
+  group?: string | null;
+  draft?: boolean;
   extra?: Record<string, unknown>;
 }
 
 export interface Snippet extends SnippetMeta {
-  markdown: string;
   html: string;
+  raw?: string;
+  markdown?: string;
 }
 
-export type SnippetFilter = (snippet: SnippetMeta) => boolean;
-
-export interface ListOptions {
-  filter?: SnippetFilter;
-  limit?: number;
-  offset?: number;
+export interface SnippetSearchFilter {
+  type?: string;
+  group?: string;
+  tags?: string[];
+  tagsMode?: "any" | "all";
 }
 
 export type ManifestSource =
@@ -28,19 +28,22 @@ export type ManifestSource =
   | SnippetMeta[]
   | (() => Promise<SnippetMeta[]> | SnippetMeta[]);
 
-export interface SnippetClientOptions {
-  /** Where to load the manifest; defaults to `/snippets-index.json`. */
-  manifest: ManifestSource;
-  /** Custom fetch to use in Node environments. Falls back to global `fetch`. */
-  fetcher?: (input: string) => Promise<ResponseLike>;
-  /** Allows overriding markdown → HTML rendering. Defaults to `marked`. */
-  markdownRenderer?: (markdown: string) => Promise<string> | string;
-  /** Customize how snippet URLs are resolved; defaults to the manifest `path`. */
-  resolveSnippetPath?: (meta: SnippetMeta) => string;
-}
-
 export interface ResponseLike {
   ok: boolean;
   status: number;
   text(): Promise<string>;
 }
+
+export type SnippetFetcherResult = string | ResponseLike;
+
+export type SnippetFetcher = (url: string) => Promise<SnippetFetcherResult>;
+
+export interface SnippetClientOptions {
+  manifest: ManifestSource;
+  base?: string;
+  fetch?: SnippetFetcher;
+  frontMatter?: boolean;
+  cache?: boolean;
+  verbose?: boolean;
+  render?: (markdown: string) => string | Promise<string>;
+}

package/tsup.config.ts

@@ -4,16 +4,19 @@ export default defineConfig([
   {
     entry: {
       index: "src/index.ts",
-      slug: "src/slug.ts"
+      slug: "src/slug.ts",
+      inline: "src/inline.ts",
+      "angular/index": "src/angular/index.ts"
     },
-    format: ["esm", "cjs"],
+    format: ["esm"],
     dts: true,
     sourcemap: true,
     clean: true,
     target: "es2020",
-    outExtension({ format }) {
+    external: ["@angular/core", "@angular/common", "@angular/router", "@angular/platform-browser", "rxjs"],
+    outExtension() {
       return {
-        js: format === "cjs" ? ".cjs" : ".mjs"
+        js: ".js"
       };
     }
   },
@@ -33,5 +36,24 @@ export default defineConfig([
         js: ".js"
       };
     }
+  },
+  {
+    entry: {
+      "mark-down-inline": "src/inline.ts"
+    },
+    format: ["iife"],
+    globalName: "markDownInline",
+    dts: false,
+    sourcemap: true,
+    clean: false,
+    platform: "browser",
+    minify: false,
+    target: "es2018",
+    splitting: false,
+    outExtension() {
+      return {
+        js: ".umd.js"
+      };
+    }
   }
 ]);