open-index/open-npm huggingface dataset:
npm package: @synstack/fs-cache
Description: Human-friendly file system caching
Author: pAIrprog
Latest version: 1.5.10

# @synstack/fs-cache

Human-friendly file system caching

## What is it for?

Sometimes you need to cache expensive function results between program runs. This package makes it easy to cache function outputs to disk with type safety while keeping the file system clean and cache entries readable.

```typescript
import { fsCache } from "@synstack/fs-cache";

// Create a cache in the .cache/expensive/function.json file
const cache = fsCache(".cache").key(["expensive", "function"]).pretty(true);

// Cache an expensive function
const cachedExpensiveFunction = cache.fn(expensiveFunction);
```

## Caching philosophy

The idea is to generate cache entries without poluting the file system with expired entries. This requires a two-step matching process:

- First file is matched based on the key defined with `key()`
- If the file exists, a second check is done based on input parameters and can be customized with `signatureFn()` which defaults to [`deepEqual`](#Deep-Equality)
- If it matches, the output is returned from the cache
- If it doesn't match or the file doesn't exist, the function is called, the output is cached, and then returned

## Installation

```bash
# Using npm
npm install @synstack/fs-cache

# Using yarn
yarn add @synstack/fs-cache

# Using pnpm
pnpm add @synstack/fs-cache
```

## Features

### [@synstack/fs](../fs/README.md) interoperability

Cache directory can be initialized using an `FsDir` instance:

```typescript
import { fsDir } from "@synstack/fs";

const cacheDir = fsDir(".cache");
const cache = fsCache(cacheDir);
```

### Function Caching

Cache expensive function results with type safety:

```typescript
import { fsCache } from "@synstack/fs-cache";

const cache = fsCache(".cache");

// Cache with static key
const cachedFn = cache.key(["myFunction"]).fn((x: number) => x * x);
```

### Cache Control

Fine-grained control over cache behavior:

```typescript
// Pretty-print cached JSON
const cache = fsCache(".cache").pretty(true);

// Custom cache signature generation
const cache2 = fsCache(".cache")
  .signatureFn((arg: string) => arg.toLowerCase())
  .key(["normalized"]);

// Lock cached values
await cache.lock(true, ["key"]); // Prevent updates
await cache.lock(false, ["key"]); // Allow updates

// Manual cache operations
const [status, value] = await cache.get(["key"]);
await cache.set(["key"], "value");

// Set a default cache value if the file doesn't exist
await cache.setDefault(["key"], "default");
```

## Deep Equality

A custom deep equality function is provided.
The only custom behavior implemented, is that objects with undefined values are considered equal to objects with matching missing values.

```typescript
import { deepEqual } from "@synstack/fs-cache";

deepEqual({ a: undefined }, {}); // true
```
npm package: @synstack/git
Description: Git utilities for AI prompting and automation
Author: pAIrprog
Latest version: 1.3.1

# @synstack/git

Git utilities for AI prompting and automation

> [!NOTE]
> The `ls` function is available through [@synstack/fs](../fs/README.md) for convenience.

## What is it for?

This package provides a small set of Git operations commonly needed when working with AI tools and automation scripts:

```typescript
import { ls, show } from "@synstack/git";

// Get all git-relevant files in your project
const files = await ls();

// View specific commit changes
const commitDetails = await show("449b7730436026243936a0a2f37c6d3474fcad3b");
```

## Installation

```bash
npm install @synstack/git
# or
yarn add @synstack/git
# or
pnpm add @synstack/git
```
npm package: @synstack/glob
Description: Glob pattern matching and file filtering utilities
Author: pAIrprog
Latest version: 1.3.0

# @synstack/glob

Glob pattern matching and file filtering utilities

> [!NOTE]
> Glob search on directories is available through [@synstack/fs](../fs/README.md) for convenience.

## What is it for?

When you need to find files using glob patterns or filter paths based on patterns, this package provides type-safe utilities:

```typescript
import { glob, matches } from "@synstack/glob";

// Find all TypeScript files
const files = await glob.cwd("./src").find("**/*.ts");
console.log(files);
// ["src/index.ts", "src/utils.ts"]

// Check if a file matches a pattern
const isMatch = matches("src/file.ts", "**/*.ts");
console.log(isMatch); // true

// Exclude test files
const nonTestFiles = await glob.cwd().find(["**/*.ts", "!**/*.test.ts"]);
```

## Installation

```bash
# Using npm
npm install @synstack/glob

# Using yarn
yarn add @synstack/glob

# Using pnpm
pnpm add @synstack/glob
```

## Features

### File Finding

Find files using glob patterns with support for exclusions:

```typescript
import { glob } from "@synstack/glob";

// Find all files in a directory
const allFiles = await glob.cwd("./src").find("**/*");

// Find with multiple patterns
const tsFiles = await glob.cwd().find([
  "**/*.ts", // Include TypeScript files
  "!**/*.test.ts", // Exclude test files
  "!**/node_modules/**", // Exclude node_modules
]);

// Synchronous finding
const configFiles = glob.cwd().findSync("**/*.config.ts");
```

### Pattern Matching

Check if paths match glob patterns:

```typescript
import { matches, filterFactory } from "@synstack/glob";

// Simple matching
matches("src/file.ts", "**/*.ts"); // true
matches("test/file.ts", "!test/**"); // false

// Create reusable filters
const filter = filterFactory([
  "**/*.ts", // Include TypeScript
  "!**/*.test.ts", // Exclude tests
]);

filter("src/utils.ts"); // true
filter("src/test.test.ts"); // false
```

### Pattern Capturing

Extract values from glob patterns:

```typescript
import { capture } from "@synstack/glob";

// Capture values from paths
const values = capture("**/(*)/(*).ts", "src/utils/format.ts");
console.log(values); // ["utils", "format"]
```
npm package: @synstack/markdown
Description: Opinionated Markdown utilities
Author: pAIrprog
Latest version: 1.3.7

# @synstack/markdown

Type-safe markdown processing with YAML frontmatter support

## What is it for?

This package provides tools for:

- Converting HTML to markdown
- Managing YAML frontmatter with type-safe data
- Handling markdown content

```typescript
import { fromHtml, MdDoc } from "@synstack/markdown";

// Convert HTML to markdown
const markdown = fromHtml("<h1>Hello</h1>");
// Returns: "# Hello"

// Work with markdown documents and frontmatter
interface PostFrontmatter {
  title: string;
  date: string;
}

const doc = MdDoc.withOptions({ schema: postSchema }).fromString(`---
title: Hello World
date: 2024-01-01
---
# Content here`);

// Access typed frontmatter data
console.log(doc.data.title); // "Hello World"

// Update content while preserving frontmatter
const updated = doc.setBody("# New content");
```

## Installation

```bash
# Using npm
npm install @synstack/markdown

# Using yarn
yarn add @synstack/markdown

# Using pnpm
pnpm add @synstack/markdown
```

## Features

### HTML to Markdown Conversion

Convert HTML content to markdown with consistent styling:

```typescript
import { fromHtml } from "@synstack/markdown";

const markdown = fromHtml("<h1>Title</h1><p>Content</p>");
// Returns:
// # Title
//
// Content
```

### YAML Frontmatter Handling

Work with YAML frontmatter in markdown documents:

```typescript
import { getHeaderData, setHeaderData } from "@synstack/markdown";

// Extract frontmatter data
const data = getHeaderData("---\ntitle: Hello\n---\n# Content");
// Returns: { title: "Hello" }

// Set frontmatter data
const text = setHeaderData("# Content", { title: "Hello" });
// Returns: "---\ntitle: Hello\n---\n# Content"
```

### Type-safe Document Management (MdDoc)

Handle markdown documents with type-safe frontmatter:

```typescript
import { MdDoc } from "@synstack/markdown";

// Create from markdown string
const doc = MdDoc.fromString(`---
title: Hello
---
# Content`);

// Create from HTML
const htmlDoc = MdDoc.fromHtml("<h1>Title</h1>");

// Update content
const updated = doc
  .setData({ title: "New Title" })
  .setBody("# Updated content");
```

### Markdown Formatting

Format markdown content for different purposes:

```typescript
import { MdDoc } from "@synstack/markdown";

const doc = MdDoc.fromString(`# Title
Some content`);

// Minify for LLM processing
const minified = doc.minify().toMd();

// Beautify for human readability
const beautified = doc.beautify().toMd();
```