open-index/open-npm huggingface dataset:
npm package: @punkish/zcache
Description: a zemantic file-based cache
Author: Puneet Kishor
Latest version: 2.5.0

# zcache

A zemantic, ~~no-dependency,~~ file-based cache

There are loads of wonderful, battle-tested caching modules. This is not one of them. But, if you want a ~~no-dependency,~~ file-based cache that can store both semantic and non-semantic queries, this one is for you. A really zimple, zemantic caching module. The only dependency is `@huggingface/transformers` using the `Supabase/gte-small` model for generating embeddings.

![architecture](assets/zcache.svg)

![flow](assets/semcache.svg)

Create a cache

```
import { Cache } from '@punkish/zcache';

const options = {
    dir: './cache',
    segment: 'default',
    ttl: 86400000
    similarityThreshold: 0.9
};

// Create a new cache with options
const cache = new Cache(options);

// Initialize the cache
await cache.init();
```

Cache a semantic query

```
const query1 = 'What is the speed of a swallow?';
const response1 = 500;
const isSemantic = true;
const res = await cache.set({ 
    query: query1, 
    response: response1, 
    isSemantic 
});
console.log(res);
// {
//     query: "What is the speed of a swallow?",
//     response: 500,
//     stored: <date>
//     ttl: 86400000
// }
```

Cache a non-semantic query

```
const query2 = 'Half of 1000';
const response2 = 500;
const res = await cache.set({ 
    query: query2, 
    response: response2 
});
console.log(res);
// {
//     query: "Half of 1000",
//     response: 500,
//     stored: <date>
//     ttl: 86400000
// }
```

Retrieve the values

```
const res1 = await cache.get({ query: query2 });
console.log(res1);
// {
//     query: "Half of 1000",
//     response: 500,
//     stored: <date>
//     ttl: 86400000
// }
const res2 = await cache.get({ query: query1, isSemantic });
console.log(res2);
// {
//     query: "What is the speed of a swallow?",
//     response: 500,
//     stored: <date>
//     ttl: 86400000
// }
```

Retrieve another semantic query

```
const query3 = 'How fast does the swallow fly?';
const res = await cache.get({ query: query3, isSemantic });
console.log(res);
// {
//     query: "What is the speed of a swallow?",
//     response: 500,
//     stored: <date>
//     ttl: 86400000
// }
```
npm package: @punkish/zconfig
Description: a zimple config utility
Author: Puneet Kishor
Latest version: 1.0.4

# zconfig

There are lots of wonderful utilities for storing and managing config information. This is not one of them. But, if you want a dependency-free utility, consider using this, a really zimple tool that works for me.

## How To

Initialize a new config instance and access the settings as follows

```js
import { Config } from './index.js';
const config = new Config().settings;
console.log(config)
```

See the accompanying `example.js` and the sample settings in [config](config/) directory. The base setting in `development.cjs` (or `default.cjs`) is always read first. Then, depending on the `process.env.NODE_ENV`, the applicable `test.cjs` or `production.cjs` are deep-merged into the base settings. All the settings are available via the resulting `config` object.

`process.env.NODE_ENV` can be passed in via [dotenv](https://www.npmjs.com/package/dotenv) or by any other method setting the `NODE_ENV` environment variable. For example, by prefixing the call for your program as `$ NODE_ENV=production node index.js`

**Important Notes:**

- the **config** directory has to be at the root of your application.
- the settings have to use `module.exports` and have to have the `.cjs` suffix.
npm package: @punkish/zlogger
Description: a very, very zimple logger
Author: Puneet Kishor
Latest version: 1.1.1

# zlogger
*a realy zimple logger*

There are a lot of wonderful loggers that do a lot of things. This is not one of them. This is a zero-dependency, 3.9KB (135 lines), synchronous logger, basically just a wrapper around `process.stdout.write`. It has loglevels and transports and can output log in color.

1. import the logger class. If your script is in a CommonJS format, rename it with `.mjs` extension.
    ```js
    import { Zlogger } from '@punkish/zlogger';
    ```

2. create a new logger with options
    ```js
    const log = new Zlogger({

        // log levels can be
        //  'debug', 'info', 'warn', 'error', 'fatal'
        //  'info' is the default log level
        level: 'info', 

        // transports are where the log is written
        //   'console' always exists in development
        //   'file' is optional
        transports: [ 'console', 'file' ],

        // 'mode' is optional and chooses between streams and appendFile,
        // defaulting to streams if none is provided
        mode: 'streams',

        // 'dir' is optional and used when transport is 'file'
        // if no 'dir' is provided then 'logs' is used
        dir: 'path/to/logdir',

        // 'timestamp' on every log line can be 'timeonly', 'dateonly' or 
        // defaults to 'datetime'
        tsType: 'timeonly'
    });
    ```

3. log away
    ```js
    log.info(`logger level is ${log.level()}`);
    log.info('foo');
    log.info('do something and wait… ', 'start');
    log.info('finished something\n', 'end');
    log.info('no front matter\n', 'end');
    log.warn('oops');
    log.error('uh oh!');
    log.fatal('died');
    log.setLevel('error');
    log.info(`logger level is ${log.level()}`);
    log.info('foo');
    log.info('hello… ', 'start');
    log.info('done\n', 'end');
    log.warn('oops');
    log.error('log-level changed to "error" and above');
    log.fatal('died again');
    ```
    The optional 'start' and 'end' position flags output the log message on the same line (in this case, you have to add the `\n` newline explicitly when the 'pos' is 'end'). If no log invocation with 'start' is provided, but an 'end' is provided, then no front matter is printed.
    
    In the example shown above, the output will be
    ```log
    test/index.test.js:() [19] 18:34:16.291 –  INFO logger level is INFO
    test/index.test.js:() [20] 18:34:16.295 –  INFO foo
    test/index.test.js:() [21] 18:34:16.295 –  INFO do something and wait… finished something
    no front matter
    test/index.test.js:() [32] 18:34:16.295 –  WARN oops
    test/index.test.js:() [33] 18:34:16.295 – ERROR uh oh!
    test/index.test.js:() [34] 18:34:16.295 – FATAL died
    test/index.test.js:() [41] 18:34:16.295 – ERROR log-level changed to "error" and above
    test/index.test.js:() [42] 18:34:16.295 – FATAL died again
    ```