Merge pull request #7 from srav001/0.1.4

0.1.4

Author: srav001

.prettierrc

@@ -1,9 +1,9 @@
 {
-	"useTabs": true,
-	"tabWidth": 4,
-	"singleQuote": true,
-	"trailingComma": "none",
-	"printWidth": 120,
-	"plugins": ["prettier-plugin-organize-imports", "prettier-plugin-svelte"],
-	"overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
+  "useTabs": true,
+  "tabWidth": 4,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "printWidth": 120,
+  "plugins": ["prettier-plugin-organize-imports", "prettier-plugin-svelte"],
+  "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
 }

DOCS/doc1.md

@@ -0,0 +1,67 @@
+# Documentation for Store Creation and Caching Functions
+
+This documentation provides a comprehensive overview of the TypeScript functions designed for creating stores and handling their caching. These functions are part of a larger system that manages state across an application. Below, you will find detailed descriptions, usage examples, and explanations of the parameters and return types for each function.
+
+## Functions Overview
+
+- **createStore**: Creates a primitive store with a specified name and initial state, with optional caching.
+- **createState**: A helper function that initializes the store state and handles caching based on provided options.
+- **handleCacheOfNewStore**: Manages the caching logic for a new store, including setting and retrieving cache data.
+
+### createStore
+
+Creates a primitive store with a specified name and initial state. It optionally configures caching for the store if specified in the options.
+
+#### Parameters
+
+- `storeName` (string): The name of the store being created. This name must be unique across the application.
+- `storeState` (InferedState): The initial state or value that will be stored in the created store. This is the data that the store will manage and provide access to.
+- `options` (StoreOptions, optional): Additional configuration options for creating the store. This may include settings for caching.
+
+#### Returns
+
+- `PrimitiveStore<InferedState>`: An object representing the created store. It includes the store name and a getter function for the store value.
+
+#### Usage Example
+
+```typescript
+const userStore = createStore('user', { name: 'John Doe', age: 30 });
+console.log(userStore.name); // Output: 'user'
+console.log(userStore.value); // Output: { name: 'John Doe', age: 30 }
+```
+
+### createState
+
+A helper function that initializes the store state and optionally handles caching based on the provided options. It is used internally by `createStore`.
+
+#### Parameters
+
+- `storeName` (string): The name of the store being created.
+- `storeState` (T): The initial state of the store.
+- `options` (StoreOptions, optional): Configuration options for the store, potentially including caching settings.
+
+#### Usage Example
+
+This function is used internally by `createStore` and is not intended to be called directly in most cases.
+
+### handleCacheOfNewStore
+
+Manages the caching logic for a new store, including setting and retrieving cache data based on the provided options.
+
+#### Parameters
+
+- `storeName` (string): The name of the store for which caching is being handled.
+- `storeState` (T): The initial state of the store.
+- `options` (StoreOptions): Configuration options for the store, including caching settings.
+
+#### Usage Example
+
+This function is used internally by `createState` when caching options are provided and is not intended to be called directly in most cases.
+
+## Additional Notes
+
+- The `StoreOptions` type should be defined elsewhere in your codebase, detailing the structure for caching options and any other store configuration settings.
+- The `_stores` object and `cacheModule` are assumed to be part of the larger application context, managing the state and caching logic respectively.
+- Error handling is implemented to ensure unique store names and the presence of required parameters.
+
+By utilizing these functions, developers can efficiently manage application state with the added benefit of caching, enhancing performance and user experience.

DOCS/doc2.md

@@ -0,0 +1,81 @@
+# TypeScript Documentation
+
+This documentation provides a comprehensive overview of a TypeScript module designed for state management with caching capabilities. The module introduces several key functions: `get`, `update`, `subscribe`, and `clearCache`, each serving a unique purpose in managing and interacting with state stores.
+
+## Table of Contents
+
+- [PrimitiveStore Type](#primitivestore-type)
+- [Getter Function](#getter-function)
+- [Updater Function](#updater-function)
+- [Subscriber Type](#subscriber-type)
+- [Subscribe Function](#subscribe-function)
+- [ClearCache Function](#clearcache-function)
+
+### PrimitiveStore Type
+
+Before diving into the functions, it's essential to understand the `PrimitiveStore<T>` type, which is a generic type representing a store that holds a value of type `T`. This type is crucial for the operation of the provided functions.
+
+### Getter Function
+
+```typescript
+function get<T, U>(store: PrimitiveStore<T>, derivation: (state: T) => U): Getter<U>
+```
+
+The `get` function is designed to create a getter function from a store and a derivation function. It applies the derivation function to the store's value, returning a new value of type `U`.
+
+- **Parameters:**
+  - `store`: An instance of `PrimitiveStore<T>`.
+  - `derivation`: A function that takes the current state of type `T` and returns a value of type `U`.
+
+- **Returns:** A `Getter<U>` function that, when called, returns a value of type `U`.
+
+### Updater Function
+
+```typescript
+function update<T, U, C = unknown>(store: PrimitiveStore<T>, mutator: (state: T, payload: C) => U): Updater<C>
+```
+
+The `update` function updates the store's value using a mutator function and a payload. It also handles caching if applicable.
+
+- **Parameters:**
+  - `store`: A `PrimitiveStore<T>` object.
+  - `mutator`: A function that updates the state of the store based on the provided payload.
+
+- **Returns:** An `Updater<C>` function that takes a payload of type `C`.
+
+### Subscriber Type
+
+```typescript
+type Subscriber<T, U = unknown> = (state: T) => U;
+type Subscribers<T> = Subscriber<T, unknown>[];
+```
+
+Subscribers are functions that subscribe to changes in the store's state, reacting to updates.
+
+### Subscribe Function
+
+```typescript
+function subscribe<T, U extends Subscribers<T>>(store: PrimitiveStore<T>, subscribers: [...U], effect: (states: MapSources<U, T>) => void): () => void
+```
+
+The `subscribe` function allows subscribing to a primitive store with specified subscribers and an effect to be executed.
+
+- **Parameters:**
+  - `store`: A `PrimitiveStore<T>`.
+  - `subscribers`: An array of subscriber functions.
+  - `effect`: A function that performs an action based on the states provided.
+
+- **Returns:** A cleanup function to unsubscribe the effect.
+
+### ClearCache Function
+
+```typescript
+function clearCache(storeName: string): void
+```
+
+The `clearCache` function clears the cache for a specific store if it exists.
+
+- **Parameters:**
+  - `storeName`: The name of the store to clear from the cache.
+
+This module provides a robust solution for managing state in TypeScript applications, with features like caching and subscription to state changes, enhancing performance and reactivity.

DOCS/doc3.md

@@ -0,0 +1,153 @@
+## ❗️ In Development ❗️
+
+The project is still in development. Hoping to release it right before Svelte 5 release. You can find usable examples in `src/routes/+page.svelte`.
+
+# katai
+
+Kaṭai (meaning store in Tamil) is a simple and lightweight store implementation for Svelte 5.
+
+The basics of Katai is a few primitives that can be used to build any type of store. You can also build the store type you need with the help of these primitives. We also provide a few pre-built variations to choose from the Stores options. Whichever feels the most suitable can be used.
+
+We do not wish to restrict you to a particular pattern for all your stores. You can copy the one of the current stores implementation as a base and build from on top it.
+
+## Primitives
+
+### createStore
+
+The function `createStore` creates a primitive store with a specified name and initial state.
+
+- @param {string} storeName - The `storeName` parameter is a string that represents the name of the store being created. It is a required parameter for creating a new store.
+- @param {InferedState} storeState - The `storeState` parameter in the `createStore` function represents the initial state or value that will be stored in the created store. It is the data that the store will manage and provide access to.
+- @param {StoreOptions} [options] - The `options` parameter in the `createStore` function is an optional parameter that allows you to provide additional configuration options for creating the store. It is of type `StoreOptions`, which likely contains properties or settings that can be used to customize the behavior of the store creation process like adding cache adapters.
+- @returns A PrimitiveStore object with the store name and a getter function for the store value.
+
+#### EXAMPLE
+
+```ts
+export const counterCoreStore = createStore('test', {
+  counter: 0
+});
+
+// Returns
+PrimitiveStore<{
+  counter: number;
+}>;
+```
+
+### get
+
+The `get` function takes a store and a derivation function, and returns a getter function that applies the derivation function to the store's value.
+
+- @param store - `PrimitiveStore<T>` is a generic type representing a store that holds a value of type `T`. It seems like the `store` parameter is expected to be an instance of this `PrimitiveStore` type.
+- @param derivation - The `derivation` parameter is a function that takes the current state of type `T` as input and returns a value of type `U`. It is used to derive a new value based on the current state stored in the `PrimitiveStore`.
+- @returns A `Getter<U>` function is being returned. This function takes no arguments and returns a value of type `U`. The value returned is the result of applying the `derivation` function to the `store.value`.
+
+### update
+
+The function `update` takes a store, a mutator function, and a payload, and updates the store's value using the mutator function while handling caching if applicable.
+
+- @param store - The `store` parameter is a PrimitiveStore object that holds a value of type T.
+- @param mutator - The `mutator` parameter is a function that takes the current state of the store (`T`) and a payload of type `C`, and returns a new state of type `U`. It is used to update the state of the store based on the provided payload.
+- @returns The `update` function returns an `Updater` function that takes a value of type `C` as an argument.
+
+### subscribe
+
+The `subscribe` function allows for subscribing to a primitive store with specified subscribers and an effect to be executed.
+
+- @param store - The `store` parameter is a PrimitiveStore that holds the state of type T.
+- @param subscribers - Subscribers are functions that subscribe to changes in the store's state. They are typically used to extract specific pieces of state from the store and react to changes in those pieces of state.
+- @param effect - The `effect` parameter in the `subscribe` function is a function that takes a `MapSources` object as its argument and performs some action based on the states provided in the `MapSources` object.
+- @returns The `subscribe` function returns a cleanup function that can be used to unsubscribe the effect and remove it from the list of subscribers.
+
+#### EXAMPLE
+
+```ts
+export const test = createStore('test', {
+  counter: 0
+});
+
+type StoreType = (typeof test)['value'];
+
+export const testStore = {
+  get $value() {
+    return test.value;
+  },
+  get: <U extends unknown>(derivation: (val: StoreType) => U) => get(test, () => derivation(test.value)),
+  subscribe: <T extends Subscribers<StoreType>>(states: [...T], effect: (states: MapSources<T, StoreType>) => void) =>
+    subscribe(test, states, effect)
+};
+
+testStore.subscribe([(state) => state.counter], ([value]) => {
+  console.log('counter', value);
+});
+
+const interval = setInterval(() => {
+  testStore.$value.counter = testStore.$value.counter + 1;
+}, 2000);
+
+// cleanup
+onDestroy(() => {
+  clearInterval(interval);
+});
+```
+
+## Stores
+
+### Basic Store
+
+The function `createBasicStore` creates a basic store with state, getters, and actions based on the provided options.
+
+- @param {string} storeName - The `storeName` parameter is a string that represents the name of the store being created.
+- @param options - The `options` parameter in the `createBasicStore` function is an object that contains the following properties:
+- @param {StoreOptions} [settings] - The `settings` parameter in the `createBasicStore` function is an optional parameter of type `StoreOptions`. It allows you to provide additional settings or configurations for the store creation process. These settings can include options such as the store's persistence mechanism using cache adapters.
+- @returns The `createBasicStore` function returns an object of type `BasicStore<S, G, A>`, which includes the state, getters, actions, and additional methods like `clearCache` and `subscribe`.
+
+#### EXAMPLE
+
+```ts
+const newStore = createBasicStore('tester', {
+  state: {
+    counter: 0,
+    count: 0
+  },
+  getters: {
+    getCounter: (state) => state.counter,
+    getCount: (state) => String(state.count)
+  },
+  actions: {
+    updateCounter: (state, payload: number) => {
+      state.counter += payload;
+    },
+    updateCount: (state, payload: number) => {
+      state.count += payload;
+    }
+  }
+});
+
+const interval = setInterval(() => {
+  newStore.updateCounter(1);
+}, 2000);
+
+// cleanup
+onDestroy(() => {
+  clearInterval(interval);
+});
+
+newStore.subscribe([(state) => state.counter], (states) => {
+  console.log('newStore', states[0]);
+});
+```
+
+### Writable Store
+
+The `createWritable` function creates a writable store with initial value and provides methods for getting, setting, updating, subscribing to changes, and clearing cache.
+
+- @param {T} initalValue - The `initalValue` parameter is the initial value that will be stored in the writable store. It should be an object of type `T`, which extends `Record<string, any>`. This initial value will be used as the starting value for the store.
+- @param storeName - The `storeName` parameter is a string that represents the name of the store where the data will be stored. If no `storeName` is provided, a random string will be generated for the store name.
+- @param {StoreOptions} [storeOptions] - The `storeOptions` parameter in the `createWritable` function is an optional parameter that allows you to specify additional options for the store creation. These options can include configuration settings or options specific to the underlying store implementation. If provided, these options will be used when creating the store using the `create
+- @returns An object is being returned with the following properties:
+- - get: a function that retrieves the current value from the store
+- - set: a function that updates the value in the store
+- - update: a function that takes a callback to update the value in the store
+- - subscribe: a function that subscribes to changes in the store and calls a subscriber function
+- - clearCache: a function that

DOCS/doc4.md

@@ -0,0 +1,61 @@
+# Documentation for `createBasicStore` Function
+
+The `createBasicStore` function is designed to create a basic store structure in TypeScript, facilitating state management in applications. This function is part of a larger library that provides utilities for creating, managing, and interacting with stores. Below is a detailed documentation of the `createBasicStore` function, including its parameters, return type, and usage examples.
+
+## Function Signature
+
+```typescript
+function createBasicStore<S extends State, G extends Getters<S>, A extends Actions<S>>(
+    storeName: string,
+    options: Store<S, G, A>,
+    settings?: StoreOptions
+): BasicStore<S, G, A>;
+```
+
+### Parameters
+
+- `storeName: string`: A string that represents the name of the store being created. This name is used internally for identification and possibly for caching purposes.
+
+- `options: Store<S, G, A>`: An object that specifies the initial state, getters, and actions for the store. The `options` object must conform to the `Store` type, which is a generic type parameterized by the state `S`, getters `G`, and actions `A`.
+
+  - `state: S`: The initial state of the store. It is a record type with keys as `string` or `number` and values of any type.
+  - `getters: G`: An object containing getter functions. Each getter function takes the current state as an argument and returns a computed value based on that state.
+  - `actions: A`: An object containing action functions. Each action function is responsible for updating the state based on the given payload.
+
+- `settings?: StoreOptions` (Optional): An optional parameter that allows providing additional settings or configurations for the store creation process. These settings can include options such as the store's persistence mechanism using cache adapters.
+
+### Return Type
+
+- `BasicStore<S, G, A>`: The function returns an object of type `BasicStore<S, G, A>`, which includes the state, getters, actions, and additional methods like `clearCache` and `subscribe`. This object provides a simplified interface for interacting with the store, including performing state updates and subscribing to state changes.
+
+### Additional Methods
+
+- `clearCache`: A method that clears the cache associated with the store. Useful for resetting the store's state in scenarios involving caching.
+
+- `subscribe`: A method that allows subscribing to state changes. It takes a set of subscribers and an effect function, which is called whenever the subscribed state changes.
+
+## Usage Example
+
+```typescript
+// Define the initial state, getters, and actions for a simple counter store.
+const counterOptions = {
+    state: { count: 0 },
+    getters: {
+        doubleCount: (state) => state.count * 2,
+    },
+    actions: {
+        increment: (state) => ({ count: state.count + 1 }),
+        decrement: (state) => ({ count: state.count - 1 }),
+    },
+};
+
+// Create the counter store.
+const counterStore = createBasicStore('counterStore', counterOptions);
+
+// Use the store's methods.
+console.log(counterStore.doubleCount()); // Output: 0 (double of initial count)
+counterStore.increment();
+console.log(counterStore.doubleCount()); // Output: 2 (double of updated count)
+```
+
+This example demonstrates how to create a basic store for managing a counter's state, including incrementing and decrementing actions, and a getter for computing the double of the current count.