@c-time/frelio-dependency-map 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# frelio-dependency-map
+
+Type definitions and utilities for frelio dependency map files.
+
+## Installation
+
+```bash
+npm install frelio-dependency-map
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { DependencyMap, isDependencyMap } from 'frelio-dependency-map'
+import fs from 'fs'
+
+// Load a dependency map file
+const data = JSON.parse(fs.readFileSync('_dependency-map.json', 'utf-8'))
+
+// Validate the data
+if (isDependencyMap(data)) {
+  // data is now typed as DependencyMap
+  console.log('Output paths:', Object.keys(data))
+}
+```
+
+### Validation with Detailed Errors
+
+```typescript
+import { validateDependencyMap } from 'frelio-dependency-map'
+
+const result = validateDependencyMap(data)
+if (!result.valid) {
+  console.error('Validation errors:', result.errors)
+}
+```
+
+### Finding Affected Outputs
+
+```typescript
+import { findAffectedOutputs, DependencyMap } from 'frelio-dependency-map'
+
+const map: DependencyMap = {
+  '/articles/{slug}.json': ['content_types/article', 'contents/*/article/*'],
+}
+
+// Find which outputs need rebuilding when a file changes
+const affected = findAffectedOutputs(
+  map,
+  'contents/published/article/my-post.json'
+)
+console.log(affected) // ['/articles/{slug}.json']
+```
+
+### JSON Schema Validation
+
+```typescript
+import { dependencyMapSchema } from 'frelio-dependency-map/schema'
+import Ajv from 'ajv'
+
+const ajv = new Ajv()
+const validate = ajv.compile(dependencyMapSchema)
+
+if (!validate(data)) {
+  console.error(validate.errors)
+}
+```
+
+## API
+
+### Types
+
+- `DependencyMap` - Main type for dependency map objects
+- `OutputPath` - Type alias for output path strings
+- `DependencyPath` - Type alias for dependency path strings
+- `ValidationResult` - Result of validation operations
+- `ValidationError` - Individual validation error
+
+### Functions
+
+- `isDependencyMap(value)` - Type guard for DependencyMap
+- `validateDependencyMap(value)` - Validates with detailed errors
+- `getDependencyPaths(map, outputPath)` - Get dependencies for an output
+- `getOutputPaths(map)` - Get all output paths
+- `getAllDependencyPaths(map)` - Get all unique dependency paths
+- `mergeDependencyMaps(...maps)` - Merge multiple maps
+- `findAffectedOutputs(map, changedPath)` - Find outputs affected by a change
+- `createDependencyMap()` - Create an empty dependency map
+- `setDependencies(map, outputPath, deps)` - Set dependencies for an output
+- `removeDependencies(map, outputPath)` - Remove an output from the map
+
+### Constants
+
+- `DEPENDENCY_PATH_PREFIXES` - Common path prefixes
+- `dependencyMapSchema` - JSON Schema for validation
+
+## License
+
+MIT

package/dist/guards.d.ts

@@ -0,0 +1,9 @@
+import type { DependencyMap, ValidationResult } from './types.js';
+/**
+ * Type guard to check if a value is a valid DependencyMap
+ */
+export declare function isDependencyMap(value: unknown): value is DependencyMap;
+/**
+ * Validates a value as a DependencyMap and returns detailed errors
+ */
+export declare function validateDependencyMap(value: unknown): ValidationResult;

package/dist/guards.js

@@ -0,0 +1,72 @@
+/**
+ * Type guard to check if a value is a valid DependencyMap
+ */
+export function isDependencyMap(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    for (const [key, val] of Object.entries(obj)) {
+        // Key must be a non-empty string
+        if (typeof key !== 'string' || key.length === 0) {
+            return false;
+        }
+        // Value must be an array of strings
+        if (!Array.isArray(val)) {
+            return false;
+        }
+        for (const item of val) {
+            if (typeof item !== 'string') {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Validates a value as a DependencyMap and returns detailed errors
+ */
+export function validateDependencyMap(value) {
+    const errors = [];
+    if (value === null) {
+        errors.push({ path: '', message: 'Value is null' });
+        return { valid: false, errors };
+    }
+    if (typeof value !== 'object') {
+        errors.push({ path: '', message: `Expected object, got ${typeof value}` });
+        return { valid: false, errors };
+    }
+    const obj = value;
+    for (const [key, val] of Object.entries(obj)) {
+        if (typeof key !== 'string' || key.length === 0) {
+            errors.push({
+                path: key,
+                message: 'Output path must be a non-empty string',
+            });
+            continue;
+        }
+        if (!Array.isArray(val)) {
+            errors.push({
+                path: key,
+                message: `Expected array of dependencies, got ${typeof val}`,
+            });
+            continue;
+        }
+        for (let i = 0; i < val.length; i++) {
+            const item = val[i];
+            if (typeof item !== 'string') {
+                errors.push({
+                    path: `${key}[${i}]`,
+                    message: `Expected string dependency path, got ${typeof item}`,
+                });
+            }
+            else if (item.length === 0) {
+                errors.push({
+                    path: `${key}[${i}]`,
+                    message: 'Dependency path cannot be empty',
+                });
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * frelio-dependency-map
+ *
+ * Type definitions and utilities for frelio dependency map files.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DependencyMap,
+ *   isDependencyMap,
+ *   validateDependencyMap,
+ *   findAffectedOutputs
+ * } from 'frelio-dependency-map'
+ *
+ * // Load and validate a dependency map
+ * const data = JSON.parse(fs.readFileSync('_dependency-map.json', 'utf-8'))
+ *
+ * if (isDependencyMap(data)) {
+ *   // Type-safe access
+ *   const affected = findAffectedOutputs(data, 'contents/published/article/my-post.json')
+ *   console.log('Affected outputs:', affected)
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { DependencyMap, OutputPath, DependencyPath, DependencyPathPrefix, ValidationResult, ValidationError, } from './types.js';
+export { DEPENDENCY_PATH_PREFIXES } from './types.js';
+export { dependencyMapSchema } from './schema.js';
+export type { DependencyMapSchema } from './schema.js';
+export { isDependencyMap, validateDependencyMap } from './guards.js';
+export { getDependencyPaths, getOutputPaths, getAllDependencyPaths, mergeDependencyMaps, findAffectedOutputs, createDependencyMap, setDependencies, removeDependencies, } from './utils.js';

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * frelio-dependency-map
+ *
+ * Type definitions and utilities for frelio dependency map files.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DependencyMap,
+ *   isDependencyMap,
+ *   validateDependencyMap,
+ *   findAffectedOutputs
+ * } from 'frelio-dependency-map'
+ *
+ * // Load and validate a dependency map
+ * const data = JSON.parse(fs.readFileSync('_dependency-map.json', 'utf-8'))
+ *
+ * if (isDependencyMap(data)) {
+ *   // Type-safe access
+ *   const affected = findAffectedOutputs(data, 'contents/published/article/my-post.json')
+ *   console.log('Affected outputs:', affected)
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { DEPENDENCY_PATH_PREFIXES } from './types.js';
+// Schema
+export { dependencyMapSchema } from './schema.js';
+// Type guards & validation
+export { isDependencyMap, validateDependencyMap } from './guards.js';
+// Utilities
+export { getDependencyPaths, getOutputPaths, getAllDependencyPaths, mergeDependencyMaps, findAffectedOutputs, createDependencyMap, setDependencies, removeDependencies, } from './utils.js';

package/dist/schema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * JSON Schema for DependencyMap validation
+ */
+export declare const dependencyMapSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "DependencyMap";
+    readonly description: "Maps output file paths to arrays of dependency paths for incremental builds";
+    readonly type: "object";
+    readonly additionalProperties: {
+        readonly type: "array";
+        readonly items: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly description: "Array of dependency paths (glob patterns allowed)";
+    };
+    readonly examples: readonly [{
+        readonly '/articles/{slug}.json': readonly ["content_types/article", "templates/article/detail.html", "contents/*/article/*"];
+        readonly '/articles/index.json': readonly ["content_types/article", "templates/article/list.html", "contents/*/article/*"];
+    }];
+};
+export type DependencyMapSchema = typeof dependencyMapSchema;

package/dist/schema.js

@@ -0,0 +1,31 @@
+/**
+ * JSON Schema for DependencyMap validation
+ */
+export const dependencyMapSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'DependencyMap',
+    description: 'Maps output file paths to arrays of dependency paths for incremental builds',
+    type: 'object',
+    additionalProperties: {
+        type: 'array',
+        items: {
+            type: 'string',
+            minLength: 1,
+        },
+        description: 'Array of dependency paths (glob patterns allowed)',
+    },
+    examples: [
+        {
+            '/articles/{slug}.json': [
+                'content_types/article',
+                'templates/article/detail.html',
+                'contents/*/article/*',
+            ],
+            '/articles/index.json': [
+                'content_types/article',
+                'templates/article/list.html',
+                'contents/*/article/*',
+            ],
+        },
+    ],
+};

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Dependency Map type definitions
+ *
+ * A dependency map tracks which source files affect each output file,
+ * enabling incremental/differential builds.
+ */
+/**
+ * Output path pattern (e.g., "/articles/{slug}.json", "/articles/index.json")
+ * Can include template variables like {slug}, {page}, etc.
+ */
+export type OutputPath = string;
+/**
+ * Dependency path pattern
+ * Examples: "contents/*/article/*", "templates/article/detail.html"
+ * Can include glob patterns for matching multiple files.
+ *
+ * Common prefixes:
+ * - content_types/ - Content type definitions
+ * - templates/ - Template files
+ * - contents/ - Content data files (often with glob patterns)
+ */
+export type DependencyPath = string;
+/**
+ * Dependency Map
+ *
+ * Maps output file paths to arrays of dependency paths.
+ * Used by the builder for incremental builds - when any dependency changes,
+ * the corresponding output files need to be regenerated.
+ *
+ * Example:
+ * ```
+ * {
+ *   "/articles/{slug}.json": [
+ *     "content_types/article",
+ *     "templates/article/detail.html",
+ *     "contents/*/article/*"
+ *   ]
+ * }
+ * ```
+ */
+export type DependencyMap = {
+    [outputPath: OutputPath]: DependencyPath[];
+};
+/**
+ * Common dependency path prefixes used in frelio projects
+ */
+export declare const DEPENDENCY_PATH_PREFIXES: {
+    /** Content type schema definitions */
+    readonly CONTENT_TYPES: "content_types/";
+    /** Template files */
+    readonly TEMPLATES: "templates/";
+    /** Content data files */
+    readonly CONTENTS: "contents/";
+};
+export type DependencyPathPrefix = (typeof DEPENDENCY_PATH_PREFIXES)[keyof typeof DEPENDENCY_PATH_PREFIXES];
+/**
+ * Result of validation operations
+ */
+export type ValidationResult = {
+    valid: boolean;
+    errors: ValidationError[];
+};
+export type ValidationError = {
+    path: string;
+    message: string;
+};

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * Dependency Map type definitions
+ *
+ * A dependency map tracks which source files affect each output file,
+ * enabling incremental/differential builds.
+ */
+/**
+ * Common dependency path prefixes used in frelio projects
+ */
+export const DEPENDENCY_PATH_PREFIXES = {
+    /** Content type schema definitions */
+    CONTENT_TYPES: 'content_types/',
+    /** Template files */
+    TEMPLATES: 'templates/',
+    /** Content data files */
+    CONTENTS: 'contents/',
+};

package/dist/utils.d.ts

@@ -0,0 +1,36 @@
+import type { DependencyMap, DependencyPath, OutputPath } from './types.js';
+/**
+ * Gets the dependency paths for a specific output path
+ * Returns an empty array if the output path is not found
+ */
+export declare function getDependencyPaths(map: DependencyMap, outputPath: OutputPath): DependencyPath[];
+/**
+ * Gets all output paths defined in the dependency map
+ */
+export declare function getOutputPaths(map: DependencyMap): OutputPath[];
+/**
+ * Gets all unique dependency paths across all outputs
+ */
+export declare function getAllDependencyPaths(map: DependencyMap): DependencyPath[];
+/**
+ * Merges multiple dependency maps into one
+ * Later maps override earlier ones for the same output path
+ */
+export declare function mergeDependencyMaps(...maps: DependencyMap[]): DependencyMap;
+/**
+ * Finds all output paths that depend on a given dependency path
+ * Supports exact match and simple glob pattern matching
+ */
+export declare function findAffectedOutputs(map: DependencyMap, changedPath: DependencyPath): OutputPath[];
+/**
+ * Creates an empty dependency map
+ */
+export declare function createDependencyMap(): DependencyMap;
+/**
+ * Adds or updates dependencies for an output path
+ */
+export declare function setDependencies(map: DependencyMap, outputPath: OutputPath, dependencies: DependencyPath[]): DependencyMap;
+/**
+ * Removes an output path from the dependency map
+ */
+export declare function removeDependencies(map: DependencyMap, outputPath: OutputPath): DependencyMap;

package/dist/utils.js

@@ -0,0 +1,99 @@
+/**
+ * Gets the dependency paths for a specific output path
+ * Returns an empty array if the output path is not found
+ */
+export function getDependencyPaths(map, outputPath) {
+    return map[outputPath] ?? [];
+}
+/**
+ * Gets all output paths defined in the dependency map
+ */
+export function getOutputPaths(map) {
+    return Object.keys(map);
+}
+/**
+ * Gets all unique dependency paths across all outputs
+ */
+export function getAllDependencyPaths(map) {
+    const allPaths = new Set();
+    for (const paths of Object.values(map)) {
+        for (const path of paths) {
+            allPaths.add(path);
+        }
+    }
+    return Array.from(allPaths).sort();
+}
+/**
+ * Merges multiple dependency maps into one
+ * Later maps override earlier ones for the same output path
+ */
+export function mergeDependencyMaps(...maps) {
+    const result = {};
+    for (const map of maps) {
+        for (const [outputPath, deps] of Object.entries(map)) {
+            result[outputPath] = [...deps];
+        }
+    }
+    return result;
+}
+/**
+ * Finds all output paths that depend on a given dependency path
+ * Supports exact match and simple glob pattern matching
+ */
+export function findAffectedOutputs(map, changedPath) {
+    const affected = [];
+    for (const [outputPath, deps] of Object.entries(map)) {
+        for (const dep of deps) {
+            if (matchesDependencyPath(dep, changedPath)) {
+                affected.push(outputPath);
+                break;
+            }
+        }
+    }
+    return affected;
+}
+/**
+ * Checks if a dependency pattern matches a given path
+ * Supports * as a wildcard for any single path segment
+ */
+function matchesDependencyPath(pattern, path) {
+    // Exact match
+    if (pattern === path) {
+        return true;
+    }
+    // Convert glob pattern to regex
+    // * matches any characters except /
+    const regexPattern = pattern
+        .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special regex chars
+        .replace(/\*/g, '[^/]*'); // * matches any segment
+    try {
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(path);
+    }
+    catch {
+        // If regex compilation fails, fall back to exact match
+        return pattern === path;
+    }
+}
+/**
+ * Creates an empty dependency map
+ */
+export function createDependencyMap() {
+    return {};
+}
+/**
+ * Adds or updates dependencies for an output path
+ */
+export function setDependencies(map, outputPath, dependencies) {
+    return {
+        ...map,
+        [outputPath]: [...dependencies],
+    };
+}
+/**
+ * Removes an output path from the dependency map
+ */
+export function removeDependencies(map, outputPath) {
+    const { [outputPath]: _, ...rest } = map;
+    return rest;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@c-time/frelio-dependency-map",
+  "version": "1.0.0",
+  "description": "Type definitions and utilities for frelio dependency map files",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "frelio",
+    "dependency-map",
+    "typescript",
+    "types",
+    "cms"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}