import { StoreContext, 
useStore, 
JSONLStore, 
type Store, 
type StoreConstructorOptions
} from "@effection-contrib/jsonl-store"

JSONL Streaming Store

JSONL Streaming Store provides an easy way to store documents in JSONL files. This is useful when you need cache responses from HTTP requests for later processing. This API focuses on providing streaming APIs for working with the contents of the store with a glob selector syntax for choosing which files to read.

Getting Started

You can use the default store client which will write store to join(import.meta.dirname ?? Deno.cwd(), ".store").

import { run } from "npm:effection@4.0.0-alpha.3";
import { useStore } from "jsr:@effection-contrib/jsonl-store";

await run(function* () {
  const store = yield* useStore();

  console.log(store.location); // output store location
});

Custom location

You can create a custom store location by using JSONLStore.from function. It ensures that you do not forget to add a trailing forward slash to the path.

import { run } from "npm:effection@4.0.0-alpha.3";
import {
  JSONLStore,
  StoreContext,
  useStore,
} from "jsr:@effection-contrib/jsonl-store";

await run(function* () {
  const store = JSONLStore.from({
    location: `file://absolute/path/to/the/location/`,
  });
  yield* StoreContext.set(store);
});

Writing and appending to store

You can write to the store at a given key and append to the same key.

import { run } from "npm:effection@4.0.0-alpha.3";
import { useStore } from "jsr:@effection-contrib/jsonl-store";

await run(function* () {
  const store = yield* useStore();

  yield* store.write("greeting", "hello world!");
  yield* store.append("greeting", "another greeting!");
  yield* store.append("greeting", "yet another!");
});

greeting is the key and hello world! is the value. The value will be serialized to JSON on write - you do not need to worry about it. Appending content to the same file makes it easy to collocate relevant entities.

Reading

Reading values from a key produces a stream of all values from the given key.

import { run } from "npm:effection@4.0.0-alpha.3";
import { useStore } from "jsr:@effection-contrib/jsonl-store";

await run(function* () {
  const store = yield* useStore();

  for (const item of yield* each(store.read<string>("greeting"))) {
    console.log(item);
    yield* each.next();
  }
});

API

const StoreContext: Context<Store>

function* useStore(): Operation<Store>

class JSONLStore implements Store {

Creates a store with a location that has a trailing slash. The trailing slash is important to ensure that the store content is written to the store directory and not the directory above which can be very annoying. The location has to be absolute.
```
const store = JSONLStore.from({ location: 'file:///Users/foo/.store/' })
```
from(options: StoreConstructorOptions): JSONLStore;

Returns true when key is present

import { useStore } from "jsr:@effection-contrib/jsonl-store";

const store = yield* useStore();

if (yield* store.has("test")) {
 console.log("store exists");
}

has(key: string): Operation<boolean>;

Returns content of a file as a stream

import { each } from "npm:effection@4.0.0-alpha.3";
import { useStore } from "jsr:@effection-contrib/jsonl-store";

const store = yield* useStore();

for (const item of yield* each(store.read<number>("test"))) {
  console.log(item)
  yield* each.next();
}

read(key: string): Stream<T, void>;

Write data to a file, creates the file and necessary directory structure as it goes along.

import { useStore } from "jsr:@effection-contrib/jsonl-store";

const store = yield* useStore();
yield* store.write("hello", "world");

write(key: string, data: unknown): Operation<void>;

Add data to an existing file.

import { useStore } from "jsr:@effection-contrib/jsonl-store";

const store = yield* useStore();
yield* store.write("hello", "world");
yield* store.append("hello", "from bob");

append(key: string, data: unknown): Operation<void>;

Returns a stream of content from all files matching a glob

import { each } from "npm:effection@4.0.0-alpha.3";
import { useStore } from "jsr:@effection-contrib/jsonl-store";

const store = yield* useStore();

for (const item of yield* each(store.find<number>("subdir/*"))) {
  console.log(item);
   yield* each.next();
}

find(glob: string): Stream<T, void>;

clear(): Operation<void>;

}

interface Store {

location: URL;
write(key: string, data: unknown): Operation<void>;
append(key: string, data: unknown): Operation<void>;
read(key: string): Stream<T, void>;
has(key: string): Operation<boolean>;
find(glob: string): Stream<T, void>;
clear(): Operation<void>;

}

interface StoreConstructorOptions {

location: URL | string;

}