@piqit/resolvers 0.0.2

package/src/path-pattern.ts

@@ -0,0 +1,226 @@
+/**
+ * Path Pattern Parsing and Matching
+ *
+ * Parses patterns like `{year}/{slug}.md` and provides:
+ * - Type-level extraction of parameters
+ * - Glob pattern generation
+ * - Path matching to extract params
+ * - Path building from params
+ */
+
+// =============================================================================
+// Type-level Parameter Extraction
+// =============================================================================
+
+/**
+ * Extract params from a path pattern string at the type level.
+ *
+ * @example
+ * type Params = ExtractParams<'{year}/{slug}.md'>
+ * // = { year: string } & { slug: string }
+ */
+export type ExtractParams<P extends string> = P extends `${string}{${infer Param}}${infer Rest}`
+  ? { [K in Param]: string } & ExtractParams<Rest>
+  : {}
+
+/**
+ * Simplify a type by flattening intersections.
+ * Converts { a: string } & { b: string } to { a: string; b: string }
+ */
+export type Simplify<T> = { [K in keyof T]: T[K] }
+
+/**
+ * Extract and simplify params from a path pattern.
+ */
+export type PathParams<P extends string> = Simplify<ExtractParams<P>>
+
+// =============================================================================
+// Compiled Pattern Interface
+// =============================================================================
+
+/**
+ * A compiled path pattern that can match paths and generate globs.
+ */
+export interface CompiledPattern {
+  /**
+   * The original pattern string.
+   */
+  pattern: string
+
+  /**
+   * The extracted parameter names.
+   */
+  paramNames: string[]
+
+  /**
+   * Generate a glob pattern, optionally constraining specific params.
+   *
+   * @param constraints - Optional param values to use instead of wildcards
+   * @returns A glob pattern string
+   *
+   * @example
+   * pattern.toGlob()  // '** / *.md' (with {year}/{slug}.md)
+   * pattern.toGlob({ year: '2024' })  // '2024/*.md'
+   */
+  toGlob(constraints?: Record<string, unknown>): string
+
+  /**
+   * Match a path against this pattern and extract params.
+   *
+   * @param path - The file path to match (relative to base)
+   * @returns The extracted params, or null if no match
+   *
+   * @example
+   * pattern.match('2024/hello-world.md')  // { year: '2024', slug: 'hello-world' }
+   * pattern.match('invalid')  // null
+   */
+  match(path: string): Record<string, string> | null
+
+  /**
+   * Build a path from params.
+   *
+   * @param params - The param values
+   * @returns The constructed path
+   *
+   * @example
+   * pattern.build({ year: '2024', slug: 'hello' })  // '2024/hello.md'
+   */
+  build(params: Record<string, string>): string
+}
+
+// =============================================================================
+// Pattern Parsing
+// =============================================================================
+
+/**
+ * Regex to match parameter placeholders in patterns.
+ * Matches {paramName} where paramName is alphanumeric + underscores.
+ */
+const PARAM_REGEX = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g
+
+/**
+ * Characters that need escaping in regex.
+ */
+const REGEX_ESCAPE = /[.*+?^${}()|[\]\\]/g
+
+/**
+ * Compile a path pattern string into a usable pattern object.
+ *
+ * @param pattern - The pattern string like '{year}/{slug}.md'
+ * @returns A CompiledPattern instance
+ *
+ * @example
+ * const pattern = compilePattern('{year}/{slug}.md')
+ * pattern.toGlob()  // '** / *.md'
+ * pattern.match('2024/hello.md')  // { year: '2024', slug: 'hello' }
+ */
+export function compilePattern(pattern: string): CompiledPattern {
+  // Extract all parameter names in order
+  const paramNames: string[] = []
+  let match: RegExpExecArray | null
+  const regex = new RegExp(PARAM_REGEX.source, "g")
+  while ((match = regex.exec(pattern)) !== null) {
+    paramNames.push(match[1])
+  }
+
+  // Build the match regex by replacing {param} with capturing groups
+  // Each param can match anything except path separators
+  const regexPattern = pattern
+    .replace(REGEX_ESCAPE, (char) => {
+      // Don't escape our param placeholders - we'll handle them separately
+      if (char === "{" || char === "}") return char
+      return "\\" + char
+    })
+    .replace(PARAM_REGEX, "([^/]+)")
+
+  const matchRegex = new RegExp(`^${regexPattern}$`)
+
+  return {
+    pattern,
+    paramNames,
+
+    toGlob(constraints?: Record<string, unknown>): string {
+      let glob = pattern
+
+      // Replace each param with either its constrained value or a wildcard
+      for (const name of paramNames) {
+        const value = constraints?.[name]
+        if (value !== undefined && value !== null) {
+          // Use the constrained value
+          glob = glob.replace(`{${name}}`, String(value))
+        } else {
+          // Use a wildcard - * matches anything except /
+          glob = glob.replace(`{${name}}`, "*")
+        }
+      }
+
+      return glob
+    },
+
+    match(path: string): Record<string, string> | null {
+      const result = matchRegex.exec(path)
+      if (!result) return null
+
+      const params: Record<string, string> = {}
+      for (let i = 0; i < paramNames.length; i++) {
+        params[paramNames[i]] = result[i + 1]
+      }
+      return params
+    },
+
+    build(params: Record<string, string>): string {
+      let result = pattern
+      for (const name of paramNames) {
+        const value = params[name]
+        if (value === undefined) {
+          throw new Error(`Missing required param: ${name}`)
+        }
+        result = result.replace(`{${name}}`, value)
+      }
+      return result
+    },
+  }
+}
+
+// =============================================================================
+// Schema for Path Params
+// =============================================================================
+
+/**
+ * Create a StandardSchema for path params extracted from a pattern.
+ * This is used by the resolver to expose scanParams to piq core.
+ *
+ * @param pattern - The compiled pattern
+ * @returns A StandardSchema that validates param objects
+ */
+export function createParamsSchema(
+  pattern: CompiledPattern
+): import("piqit").StandardSchema<Record<string, string>> {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "piqit/resolvers",
+      validate(value: unknown) {
+        if (value === null || typeof value !== "object") {
+          return {
+            issues: [{ message: "Expected object" }],
+          }
+        }
+
+        const obj = value as Record<string, unknown>
+
+        // All params should be strings if present
+        for (const name of pattern.paramNames) {
+          const val = obj[name]
+          if (val !== undefined && typeof val !== "string") {
+            return {
+              issues: [{ message: `Param ${name} must be a string`, path: [name] }],
+            }
+          }
+        }
+
+        return { value: obj as Record<string, string> }
+      },
+    },
+  }
+}

package/src/static.ts

@@ -0,0 +1,227 @@
+/**
+ * Static Content Resolver
+ *
+ * A resolver for querying pre-compiled content in edge environments
+ * like Cloudflare Workers where filesystem access is not available.
+ *
+ * Content is compiled at build time and bundled as a static module.
+ *
+ * @example
+ * // 1. Build script compiles content:
+ * // build-content.ts
+ * import { fileMarkdown } from "@piqit/resolvers";
+ * const posts = fileMarkdown({ ... });
+ * const allPosts = await posts.resolve({ scan: {}, filter: {}, select: ["params.*", "frontmatter.*", "body.*"] });
+ * await Bun.write("src/generated/content.ts", `export const posts = ${JSON.stringify(allPosts)};`);
+ *
+ * // 2. Worker imports and uses static resolver:
+ * // worker.ts
+ * import { posts } from "./generated/content";
+ * import { staticContent } from "@piqit/resolvers";
+ * import { piq } from "piqit";
+ *
+ * const postsResolver = staticContent(posts);
+ *
+ * const results = await piq.from(postsResolver)
+ *   .filter({ author: "John" })
+ *   .select("params.slug", "frontmatter.title")
+ *   .exec();
+ */
+
+import type { Resolver, StandardSchema } from "piqit"
+
+// =============================================================================
+// Filter Helpers
+// =============================================================================
+
+/**
+ * Get a nested value from an object using dot-path notation.
+ */
+function getByPath(obj: unknown, path: string): unknown {
+  const parts = path.split(".")
+  let current: unknown = obj
+
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") {
+      return undefined
+    }
+    current = (current as Record<string, unknown>)[part]
+  }
+
+  return current
+}
+
+/**
+ * Default filter implementation - checks equality on frontmatter fields.
+ */
+function defaultFilter<T>(item: T, filter: Partial<Record<string, unknown>>): boolean {
+  const frontmatter = (item as Record<string, unknown>).frontmatter as Record<string, unknown> | undefined
+  
+  if (!frontmatter) {
+    return Object.keys(filter).length === 0
+  }
+
+  for (const [key, value] of Object.entries(filter)) {
+    if (frontmatter[key] !== value) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Check if scan constraints match params.
+ */
+function matchesScan<T>(item: T, scan: Partial<Record<string, unknown>>): boolean {
+  const params = (item as Record<string, unknown>).params as Record<string, unknown> | undefined
+  
+  if (!params) {
+    return Object.keys(scan).length === 0
+  }
+
+  for (const [key, value] of Object.entries(scan)) {
+    if (value !== undefined && params[key] !== value) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Select specific fields from an item based on select paths.
+ */
+function selectFields<T extends object>(item: T, selectPaths: string[]): Partial<T> {
+  const result: Record<string, unknown> = {}
+
+  for (const path of selectPaths) {
+    // Handle wildcards like "params.*"
+    if (path.endsWith(".*")) {
+      const namespace = path.slice(0, -2)
+      const nsValue = getByPath(item, namespace)
+      if (nsValue && typeof nsValue === "object") {
+        result[namespace] = { ...nsValue as object }
+      }
+    } else {
+      // Regular path like "params.slug" or "frontmatter.title"
+      const parts = path.split(".")
+      const namespace = parts[0]
+      
+      // Ensure namespace exists in result
+      if (!result[namespace]) {
+        result[namespace] = {}
+      }
+      
+      // Set the value
+      const value = getByPath(item, path)
+      if (parts.length === 2) {
+        (result[namespace] as Record<string, unknown>)[parts[1]] = value
+      } else {
+        // Deeper path - just copy the value
+        result[namespace] = value
+      }
+    }
+  }
+
+  return result as Partial<T>
+}
+
+// =============================================================================
+// Schema Factories
+// =============================================================================
+
+/**
+ * Create a passthrough schema that accepts any value.
+ * Used for static content where validation happened at build time.
+ */
+function createPassthroughSchema<T>(): StandardSchema<T> {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "piqit/resolvers/static",
+      validate(value: unknown) {
+        return { value: value as T }
+      },
+    },
+  }
+}
+
+// =============================================================================
+// Resolver Factory
+// =============================================================================
+
+/**
+ * Create a static content resolver from pre-compiled data.
+ *
+ * This resolver is designed for edge environments like Cloudflare Workers
+ * where filesystem access is not available. Content is compiled at build
+ * time and bundled as a static module.
+ *
+ * @param data - Array of pre-compiled content items
+ * @returns A resolver that queries the static data
+ *
+ * @example
+ * // In your worker:
+ * import { posts } from "./generated/content";
+ * import { staticContent } from "@piqit/resolvers";
+ * import { piq } from "piqit";
+ *
+ * const postsResolver = staticContent(posts);
+ *
+ * export default {
+ *   async fetch(request: Request) {
+ *     const results = await piq.from(postsResolver)
+ *       .scan({ year: "2024" })
+ *       .select("params.slug", "frontmatter.title")
+ *       .exec();
+ *
+ *     return Response.json(results);
+ *   }
+ * };
+ */
+export function staticContent<T extends object>(
+  data: T[]
+): Resolver<
+  StandardSchema<Partial<Record<string, unknown>>>,
+  StandardSchema<Partial<Record<string, unknown>>>,
+  StandardSchema<T>
+> {
+  const scanSchema = createPassthroughSchema<Partial<Record<string, unknown>>>()
+  const filterSchema = createPassthroughSchema<Partial<Record<string, unknown>>>()
+  const resultSchema = createPassthroughSchema<T>()
+
+  return {
+    schema: {
+      scanParams: scanSchema,
+      filterParams: filterSchema,
+      result: resultSchema,
+    },
+
+    async resolve(spec): Promise<Partial<T>[]> {
+      let results = [...data]
+
+      // Apply scan constraints (filter by params)
+      if (spec.scan && Object.keys(spec.scan).length > 0) {
+        results = results.filter((item) => matchesScan(item, spec.scan!))
+      }
+
+      // Apply filter constraints (filter by frontmatter)
+      if (spec.filter && Object.keys(spec.filter).length > 0) {
+        results = results.filter((item) => defaultFilter(item, spec.filter!))
+      }
+
+      // Apply select to return only requested fields
+      if (spec.select && spec.select.length > 0) {
+        return results.map((item) => selectFields(item, spec.select))
+      }
+
+      return results
+    },
+  }
+}
+
+/**
+ * Alias for staticContent - provides a more descriptive name for the use case.
+ */
+export const staticResolver = staticContent