open-index/open-npm huggingface dataset:
npm package: @iptop/node-fs-cache
Description: A lightweight file system based key-value cache with localStorage-like API
Latest version: 1.0.1

# fs-kv-cache

[中文文档](./readme-zh-cn.md)

A lightweight file system-based Key-Value cache library with a localStorage-like API.

## Features

- 🗂️ File system storage with data persistence
- 📦 MessagePack format for minimal disk usage
- 🔑 MD5 hash sharding to avoid too many files in a single directory
- 💡 localStorage-like API, simple and easy to use
- 📝 Written in JavaScript with full TypeScript support

## Installation

```bash
npm install @iptop/node-fs-cache
```

## Quick Start

```javascript
// ESM
import { FsKvCache } from '@iptop/node-fs-cache';

// CJS
const { FsKvCache } = require('@iptop/node-fs-cache');

// Create a cache instance
const cache = new FsKvCache('./cache');

// Custom directory depth (2-5 levels, default 3)
const cache2 = new FsKvCache('./cache', { depth: 2 });

// Store data
cache.setItem('username', 'john_doe');

// Retrieve data
const value = cache.getItem('username');
console.log(value); // 'john_doe'

// Check if key exists
const exists = cache.hasItem('username');
console.log(exists); // true

// Delete data
cache.removeItem('username');
```

## API

### `new FsKvCache(basePath, options?)`

Create a cache instance.

- `basePath` - Root directory path for cache file storage
- `options.depth` - Directory depth, range 2-5, default 3

### `setItem(key, value)`

Store a key-value pair.

- `key` - String key name
- `value` - Any serializable value

### `getItem(key)`

Get the value for a specified key.

- `key` - String key name
- Returns: The stored value, or `null` if the key doesn't exist

### `hasItem(key)`

Check if a key exists.

- `key` - String key name
- Returns: `boolean`

### `removeItem(key)`

Delete a key-value pair.

- `key` - String key name

## Storage Mechanism

### MD5 Hash Sharding Strategy

To avoid too many files in a single directory, MD5 hash sharding is used:

1. MD5 hash the key
   - Example: `username` → `14c4b06b824ec593239362517f538b29`

2. Create nested directory structure based on depth (default 3 levels)
   - depth=2: `cache/1/4.pack` (max 256 files)
   - depth=3: `cache/1/4/c.pack` (max 4,096 files)
   - depth=4: `cache/1/4/c/4.pack` (max 65,536 files)
   - depth=5: `cache/1/4/c/4/b.pack` (max 1,048,576 files)

### File Content Format

Uses MessagePack format, with file content as an array structure:

```javascript
[[md5Buffer, value], ...]  // md5Buffer is a 16-byte binary Buffer
```

> **Note**: To minimize storage space, cache files don't store the original key, only the MD5 binary and value. Therefore, this library doesn't provide key iteration functionality.

### Hash Collision Handling

When different keys map to the same file (same first few MD5 characters), multiple key-value pairs are stored in the same file, distinguished by the complete MD5 Buffer.

## Design Limitations

- ❌ No key iteration support (`keys()`, `entries()`, etc.)
- ❌ No browser environment support
- ❌ No async operations (synchronous API only)

## Dependencies

- [msgpackr](https://github.com/kriszyp/msgpackr) - MessagePack encoding/decoding

## License

MIT
npm package: @ipui/ipfs
Description: ipfs context for ipui
Author: octo
Latest version: 0.1.4

# @ipui/ipfs

reactjs ipfs context

> This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).

## ip[fn]s links

## description

this provider uses the ipfs-http-client to bind an entire ipfs api accesible from an react component.

## technologies

* [reactjs](https://reactjs.org)
* [ipfs](https://ipfs.io)
* [ipfs-http-client(https://github.com/ipfs/js-ipfs-http-client)

## depends on

* [@ipui/path](https://gitlab.com/ipui/ipui-path)

## how it works

* it uses the [context api](https://reactjs.org/docs/context.html) of reactjs to provide an accessible service to any component inside the context itself.

* it uses [ipfs-http-client(https://github.com/ipfs/js-ipfs-http-client) to bind a node instance.

* binds `withIpfs` on the `props` or `this.props` when is used as _consumer_.

## propTypes

| name | default | description |
| - | - | - |
| `noIpfs` | | react element that is rendered when the local `api` is unreachable |

## api

this api variables are accesible by the component that uses `withIpfs` consumer.

### address

contains the multiaddress (`/ip4/127.0.0.1/tcp/5001` by default) of the api.

### node

instance of IpfsHttpClient

### provider

```javascript
import Ipfs from '@ipui/ipfs'

const MyComponent = props => {

  return (
    <Ipfs noIpfs={ ( <h1>no local ipfs node available</h1> ) }>
      
      { /*
        your app code that requires a ipfs provider
      */}

    </Ipfs>
  )
}

export default MyComponent
```

### consumer

get node identity

```javascript
import { withIpfs } from '@ipui/ipfs'

const NodeId = props => {

  function handleClick() {
    const { id } = props.withIpfs.node
    id( ( err, identity ) => {
      if ( !err )
        console.log( identity )
    } )
  }

  return (
    <button onClick={ handleClick }>
      get node identity
    </button>
  )
}

export default withIpfs( NodeId )
```

## last updated
aug 26, 2019
npm package: @ipui/path
Description: path context for ipui
Author: octo
Latest version: 0.1.2

# @ipui/path

ipui path context

> This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).

## ip[fn]s links

## description

provide a set of tools to parse `window.location` to work with ipui.

## technologies

* [reactjs](https://reactjs.org)
* [ipfs](https://ipfs.io)

## depends on

> this is a high order context.

## how it works

* it uses the [context api](https://reactjs.org/docs/context.html) of reactjs to provide an accessible service to any component inside the context itself.

* use RouteTools to perform hash url parser and navigation tasks.

* binds `withPath` on the `props` or `this.props` when is used as _consumer_.

## api

this api variables and methods are accesible by the component that uses `withPath` consumer.

### api

api network multiaddress (`/ip4/127.0.0.1/tcp/5001`).

### current

current path `/.conf/vimrc`.

this could work with [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) to extend its capabilities.

## methods

this methods are accesible by the component that uses `withPath` consumer.

### go

> navigate between paths

**go( `path`, `options` )**

* `path` any string path such as `/me/friend/0/photo`
* `options`
  * `reload` force reload. boolean defaults to `false`.

### redirect

> alias of `go` but with `reload` defaults to `true`.

**redirect( `path` )**

* `path` is an url string.

### dirname

> get the `dirname` prefix of a given path.

**dirname( `path` )**

* `path` url string

### filename

> get the `filename` of a given path.

**filename( `path` )**

* `path` url string

### join

> like [path.join](https://nodejs.org/api/all.html#path_path_join_paths)

## usage

### provider

```javascript
import Path from '@ipui/path'

const MyComponent = props => {

  return (
    <Path>

      { /*
        your app code that requires a clipboard provider
      */}

    </Path>
  )
}

export default MyComponent
```

### consumer

`DirGoUp` component example

```javascript
import React from 'react'

import { withPath } from '@ipui/path'

import { FiCornerLeftUp } from 'react-icons/fi'

const DirGoUp = props => {

  /* functional cd */
  function cd( dir ) {
    const { dirname, join, current, go } = this.props.withPath
    if ( dir === '..' )
      dir = dirname( current )
    else
      dir = join( current, dir )

    go( dir )
  }

  /* when click just go up */
  function handleClick() {
    cd( '..' )
  }

  const { current } = props.withPath

  return (
    <>
      { current !== '/' ? (
        <button onClick={ handleClick }>
          <FiCornerLeftUp />
        </button>
      ) : null }
    </>
  )
}

export default withPath( DirGoUp )
```

## last updated
aug 26, 2019
npm package: @ipui/skin
Description: skin context for ipui
Author: octo
Latest version: 0.2.0

# @ipui/skin

this is just a skin to the project [ipfs-storage](https://gitlab.com/ipui/ipui-storage).

the idea is start to write apps that only have a little style just for layout purposes and let _sizes_ and _colors_ to be customizable with `--var` css variables.

maybe an image explains the point.

## without skin

without skin the app still shows itself as a functional but more important a "good looking" in quotes because you'll see below.

| state | preview |
| - | - |
| without skin at all, even without the base (normalization by [equalizer.css](https://www.npmjs.com/package/equalizer.css)) | ![without skin at all][without-skin-at-all] |
| only normalized | ![without skin 0][without-skin-0] |
| only normalized | ![without skin 1][without-skin-1] |

[without-skin-at-all]: ./assets/without-skin-at-all.png "without skin at all"
[without-skin-0]: ./assets/without-skin-0.png "without skin 0"
[without-skin-1]: ./assets/without-skin-1.png "without skin 1"

## actual themes

| name | preview |
| - | - |
| moon | ![moon][moon] |
| blood | ![blood][blood] |
| aqua | ![aqua][aqua] |

[moon]: ./assets/moon.png "moon"
[blood]: ./assets/blood.png "blood"
[aqua]: ./assets/aqua.png "aqua"

## last update
aug 25, 2019