@mzebley/mark-down 1.0.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mzebley/mark-down",
+  "version": "1.0.0",
+  "description": "mark↓ core runtime and shared utilities",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./slug": {
+      "types": "./dist/slug.d.ts",
+      "import": "./dist/slug.mjs",
+      "require": "./dist/slug.cjs"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "marked": "^11.1.0"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,141 @@
+installBufferShim();
+
+export * from "./index";
+
+function installBufferShim() {
+  const globalRef = globalThis as typeof globalThis & { Buffer?: BufferConstructor };
+
+  if (typeof globalRef.Buffer !== "undefined") {
+    return;
+  }
+
+  const textEncoder = new TextEncoder();
+  const textDecoder = new TextDecoder();
+
+  class BrowserBuffer extends Uint8Array {
+    constructor(value: number | ArrayBufferLike | ArrayBufferView | ArrayLike<number>) {
+      if (typeof value === "number") {
+        super(value);
+        return;
+      }
+
+      if (isArrayBufferLike(value)) {
+        super(new Uint8Array(value));
+        return;
+      }
+
+      if (ArrayBuffer.isView(value)) {
+        super(
+          new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength))
+        );
+        return;
+      }
+
+      super(Array.from(value));
+    }
+
+    override toString(encoding: BufferEncoding = "utf-8") {
+      if (encoding !== "utf-8" && encoding !== "utf8") {
+        throw new Error(`Unsupported encoding '${encoding}' in browser Buffer shim`);
+      }
+      return textDecoder.decode(this);
+    }
+  }
+
+  const from = (value: string | ArrayLike<number> | BufferSource, encoding: BufferEncoding = "utf-8") => {
+    if (typeof value === "string") {
+      if (encoding !== "utf-8" && encoding !== "utf8") {
+        throw new Error(`Unsupported encoding '${encoding}' in browser Buffer shim`);
+      }
+      return new BrowserBuffer(textEncoder.encode(value));
+    }
+
+    if (isArrayBufferLike(value)) {
+      return new BrowserBuffer(new Uint8Array(value));
+    }
+
+    if (ArrayBuffer.isView(value)) {
+      return new BrowserBuffer(value);
+    }
+
+    if (typeof (value as ArrayLike<number>).length === "number") {
+      return new BrowserBuffer(Array.from(value as ArrayLike<number>));
+    }
+
+    throw new TypeError("Unsupported input passed to Buffer.from in browser shim");
+  };
+
+  const alloc = (size: number, fill?: number | string) => {
+    if (size < 0) {
+      throw new RangeError("Invalid Buffer size");
+    }
+    const buffer = new BrowserBuffer(size);
+    if (typeof fill === "number") {
+      buffer.fill(fill);
+    } else if (typeof fill === "string") {
+      if (!fill.length) {
+        buffer.fill(0);
+      } else {
+        const pattern = textEncoder.encode(fill);
+        for (let i = 0; i < buffer.length; i++) {
+          buffer[i] = pattern[i % pattern.length];
+        }
+      }
+    } else {
+      buffer.fill(0);
+    }
+    return buffer;
+  };
+
+  const concat = (buffers: ArrayLike<Uint8Array>, totalLength?: number) => {
+    const sanitized = Array.from(buffers, (buffer) =>
+      buffer instanceof BrowserBuffer ? buffer : new BrowserBuffer(buffer)
+    );
+    const length = totalLength ?? sanitized.reduce((acc, current) => acc + current.length, 0);
+    const result = new BrowserBuffer(length);
+    let offset = 0;
+    for (const buffer of sanitized) {
+      result.set(buffer, offset);
+      offset += buffer.length;
+    }
+    return result;
+  };
+
+  const byteLength = (value: string | ArrayBuffer | ArrayBufferView) => {
+    if (typeof value === "string") {
+      return textEncoder.encode(value).length;
+    }
+    if (value instanceof ArrayBuffer) {
+      return value.byteLength;
+    }
+    if (ArrayBuffer.isView(value)) {
+      return value.byteLength;
+    }
+    throw new TypeError("Unable to determine byte length for provided value");
+  };
+
+  Object.defineProperties(BrowserBuffer, {
+    from: { value: from },
+    isBuffer: { value: (candidate: unknown) => candidate instanceof BrowserBuffer },
+    alloc: { value: alloc },
+    concat: { value: concat },
+    byteLength: { value: byteLength }
+  });
+
+  BrowserBuffer.prototype.valueOf = function valueOf() {
+    return this;
+  };
+
+  globalRef.Buffer = BrowserBuffer as unknown as BufferConstructor;
+
+  if (typeof window !== "undefined" && typeof (window as typeof globalThis).Buffer === "undefined") {
+    (window as typeof globalThis & { Buffer?: BufferConstructor }).Buffer = globalRef.Buffer;
+  }
+}
+
+function isArrayBufferLike(value: unknown): value is ArrayBufferLike {
+  if (value instanceof ArrayBuffer) {
+    return true;
+  }
+  return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./snippet-client";
+export { normalizeSlug } from "./slug";

package/src/slug.ts

@@ -0,0 +1,21 @@
+const NON_ALPHANUMERIC = /[^a-z0-9]+/gi;
+const LEADING_TRAILING_DASH = /^-+|-+$/g;
+
+export function normalizeSlug(input: string): string {
+  const value = input?.trim();
+  if (!value) {
+    throw new Error("Cannot normalize an empty slug");
+  }
+
+  const normalized = value
+    .toLowerCase()
+    .replace(NON_ALPHANUMERIC, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(LEADING_TRAILING_DASH, "");
+
+  if (!normalized) {
+    throw new Error(`Slug '${input}' does not contain any alphanumeric characters`);
+  }
+
+  return normalized;
+}

package/src/snippet-client.ts

@@ -0,0 +1,215 @@
+import matter from "gray-matter";
+import { marked } from "marked";
+import type {
+  ListOptions,
+  ManifestSource,
+  ResponseLike,
+  Snippet,
+  SnippetClientOptions,
+  SnippetFilter,
+  SnippetMeta
+} from "./types";
+
+const OPTIONAL_FIELDS: Array<keyof SnippetMeta> = [
+  "title",
+  "order",
+  "type",
+  "tags",
+  "draft"
+];
+
+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 manifestPromise?: Promise<SnippetMeta[]>;
+  private 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);
+  }
+
+  async get(slug: string): Promise<Snippet | undefined> {
+    const manifest = await this.loadManifest();
+    const entry = manifest.find((snippet) => snippet.slug === slug);
+    if (!entry) {
+      return undefined;
+    }
+
+    return this.loadSnippet(entry);
+  }
+
+  async list(filter?: SnippetFilter | ListOptions, options?: ListOptions): 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;
+    }
+
+    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)));
+    }
+
+    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);
+    }
+
+    return [...items];
+  }
+
+  listByType(type: string, options?: ListOptions): Promise<SnippetMeta[]> {
+    return this.list((entry) => entry.type === type, options);
+  }
+
+  listByGroup(group: string, options?: ListOptions): Promise<SnippetMeta[]> {
+    return this.list((entry) => entry.group === group, options);
+  }
+
+  private loadSnippet(meta: SnippetMeta): Promise<Snippet> {
+    const cached = this.snippetCache.get(meta.slug);
+    if (cached) {
+      return cached;
+    }
+
+    const promise = this.fetchSnippet(meta);
+    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 rawContent = await response.text();
+    const parsed = matter(rawContent);
+    const frontMatter = sanitizeFrontMatter(parsed.data ?? {});
+    const mergedMeta = mergeFrontMatter(meta, frontMatter.meta);
+
+    const html = await this.markdownRenderer(parsed.content);
+
+    const baseExtra = mergedMeta.extra ?? {};
+    return {
+      ...mergedMeta,
+      extra: {
+        ...baseExtra,
+        ...frontMatter.extra
+      },
+      markdown: parsed.content,
+      html
+    };
+  }
+
+  private loadManifest(): Promise<SnippetMeta[]> {
+    if (!this.manifestPromise) {
+      this.manifestPromise = this.resolveManifest();
+    }
+    return this.manifestPromise;
+  }
+
+  private async resolveManifest(): Promise<SnippetMeta[]> {
+    if (Array.isArray(this.manifestSource)) {
+      return this.manifestSource;
+    }
+
+    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 raw = await this.fetchText(this.manifestSource);
+    const manifest = JSON.parse(raw);
+    if (!Array.isArray(manifest)) {
+      throw new Error("Manifest must be an array");
+    }
+    return manifest;
+  }
+
+  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 sanitizeFrontMatter(data: Record<string, unknown>) {
+  const meta: Partial<SnippetMeta> = {};
+  const extra: Record<string, unknown> = {};
+
+  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;
+    }
+  }
+
+  return { meta, extra };
+}
+
+function normalizeTags(value: unknown): string[] | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map((tag) => String(tag));
+  }
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((tag) => tag.trim())
+      .filter(Boolean);
+  }
+  return undefined;
+}
+
+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;
+    }
+  }
+  return merged;
+}
+
+async function defaultFetch(input: string): Promise<ResponseLike> {
+  const runtimeFetch = (globalThis as typeof globalThis & { fetch?: typeof fetch }).fetch;
+  if (!runtimeFetch) {
+    throw new Error("No global fetch implementation found. Provide a custom fetcher.");
+  }
+  return runtimeFetch(input);
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+export interface SnippetMeta {
+  slug: string;
+  title?: string;
+  order?: number | null;
+  type?: string;
+  tags?: string[];
+  draft?: boolean;
+  path: string;
+  group: string;
+  extra?: Record<string, unknown>;
+}
+
+export interface Snippet extends SnippetMeta {
+  markdown: string;
+  html: string;
+}
+
+export type SnippetFilter = (snippet: SnippetMeta) => boolean;
+
+export interface ListOptions {
+  filter?: SnippetFilter;
+  limit?: number;
+  offset?: number;
+}
+
+export type ManifestSource =
+  | string
+  | 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>;
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig([
+  {
+    entry: {
+      index: "src/index.ts",
+      slug: "src/slug.ts"
+    },
+    format: ["esm", "cjs"],
+    dts: true,
+    sourcemap: true,
+    clean: true,
+    target: "es2020",
+    outExtension({ format }) {
+      return {
+        js: format === "cjs" ? ".cjs" : ".mjs"
+      };
+    }
+  },
+  {
+    entry: {
+      browser: "src/browser.ts"
+    },
+    format: ["esm"],
+    dts: true,
+    sourcemap: true,
+    clean: false,
+    target: "es2020",
+    platform: "browser",
+    splitting: false,
+    outExtension() {
+      return {
+        js: ".js"
+      };
+    }
+  }
+]);