vibra 1.0.0 → 1.0.2

package/README.md

@@ -1,5 +1,7 @@
 # Vibra
 
+[![npm version](https://img.shields.io/npm/v/vibra.svg)](https://www.npmjs.com/package/vibra)
+
 > A blazing fast, type-safe, and minimal state management library for TypeScript and JavaScript. Effortless reactivity, subscriptions, and memory safety in a tiny package.
 
 ## 🚀 Features
@@ -64,13 +66,41 @@ store.set(5);
 // Both subscribers are notified
 ```
 
+### Subscription Options
+```typescript
+const store = vibra(42);
+
+// Default behavior: callback is not called on subscribe
+store.subscribe(value => console.log('Changed:', value));
+
+// With callOnSubscribe: callback is called immediately with current value
+store.subscribe(
+  value => console.log('Current:', value),
+  { callOnSubscribe: true }
+);
+
+// Useful for initializing UI or state
+const userStore = vibra({ name: 'Alice' });
+userStore.subscribe(
+  user => updateUI(user),
+  { callOnSubscribe: true } // Update UI immediately
+);
+```
+
 ## 🧩 API Reference
 
 ### `vibra<T>(initialValue: T)`
 Returns a store object with:
 - `get(): T` — Get the current value
 - `set(value: T): void` — Set a new value (notifies subscribers if changed)
-- `subscribe(callback: (value: T) => void): () => void` — Subscribe to changes (immediately calls with current value). Returns an unsubscribe function.
+- `subscribe(callback: (value: T) => void, options?: SubscribeOptions): () => void` — Subscribe to changes. Returns an unsubscribe function.
+
+#### SubscribeOptions
+```typescript
+interface SubscribeOptions {
+  callOnSubscribe?: boolean; // If true, callback is called immediately with current value
+}
+```
 
 ## 💡 Why Vibra?
 - **Ultra-lightweight**: No bloat, just state

package/dist/index.d.mts

@@ -1,3 +1,43 @@
+/**
+ * Options for subscribing to a Vibra store
+ */
+interface SubscribeOptions {
+    /**
+     * If true, the callback will be called immediately with the current value
+     * when subscribing. Defaults to false.
+     */
+    callOnSubscribe?: boolean;
+}
+/**
+ * Type for a store subscriber callback function
+ */
+type Subscriber<T> = (value: T) => void;
+/**
+ * Type for a store unsubscribe function
+ */
+type Unsubscribe = () => void;
+/**
+ * Type for a store's public API
+ */
+interface Store<T> {
+    /**
+     * Get the current value of the store
+     */
+    get(): T;
+    /**
+     * Set a new value for the store
+     * @param value - The new value to set
+     */
+    set(value: T): void;
+    /**
+     * Subscribe to changes in the store
+     * @param callback - Function to call when the value changes
+     * @param options - Optional subscription options
+     * @returns Function to unsubscribe from the store
+     */
+    subscribe(callback: Subscriber<T>, options?: SubscribeOptions): Unsubscribe;
+}
+
 /**
  * Vibra - A Simple Yet Powerful State Management Solution
  *
@@ -15,7 +55,7 @@
  *
  * @template T - The type of the state value
  * @param initialValue - The initial value for the state
- * @returns An object containing methods to interact with the state
+ * @returns A store object implementing the Store interface
  *
  * @example
  * ```typescript
@@ -36,14 +76,11 @@
  * unsubscribe();
  * ```
  */
-declare function vibra<T>(initialValue: T): {
-    get: () => T;
-    set: (value: T) => void;
-    subscribe: (callback: (value: T) => void) => () => void;
-};
+declare function vibra<T>(initialValue: T): Store<T>;
+type Vibra<T> = Store<T>;
 
-interface Main {
-    test: true;
+declare class VibraError extends Error {
+    constructor(message: string);
 }
 
-export { type Main, vibra as default };
+export { type Store, type SubscribeOptions, type Subscriber, type Unsubscribe, type Vibra, VibraError, vibra as default };

package/dist/index.d.ts

@@ -1,3 +1,43 @@
+/**
+ * Options for subscribing to a Vibra store
+ */
+interface SubscribeOptions {
+    /**
+     * If true, the callback will be called immediately with the current value
+     * when subscribing. Defaults to false.
+     */
+    callOnSubscribe?: boolean;
+}
+/**
+ * Type for a store subscriber callback function
+ */
+type Subscriber<T> = (value: T) => void;
+/**
+ * Type for a store unsubscribe function
+ */
+type Unsubscribe = () => void;
+/**
+ * Type for a store's public API
+ */
+interface Store<T> {
+    /**
+     * Get the current value of the store
+     */
+    get(): T;
+    /**
+     * Set a new value for the store
+     * @param value - The new value to set
+     */
+    set(value: T): void;
+    /**
+     * Subscribe to changes in the store
+     * @param callback - Function to call when the value changes
+     * @param options - Optional subscription options
+     * @returns Function to unsubscribe from the store
+     */
+    subscribe(callback: Subscriber<T>, options?: SubscribeOptions): Unsubscribe;
+}
+
 /**
  * Vibra - A Simple Yet Powerful State Management Solution
  *
@@ -15,7 +55,7 @@
  *
  * @template T - The type of the state value
  * @param initialValue - The initial value for the state
- * @returns An object containing methods to interact with the state
+ * @returns A store object implementing the Store interface
  *
  * @example
  * ```typescript
@@ -36,14 +76,11 @@
  * unsubscribe();
  * ```
  */
-declare function vibra<T>(initialValue: T): {
-    get: () => T;
-    set: (value: T) => void;
-    subscribe: (callback: (value: T) => void) => () => void;
-};
+declare function vibra<T>(initialValue: T): Store<T>;
+type Vibra<T> = Store<T>;
 
-interface Main {
-    test: true;
+declare class VibraError extends Error {
+    constructor(message: string);
 }
 
-export { type Main, vibra as default };
+export { type Store, type SubscribeOptions, type Subscriber, type Unsubscribe, type Vibra, VibraError, vibra as default };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  VibraError: () => vibra_error_default,
   default: () => vibra_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -28,12 +29,10 @@ module.exports = __toCommonJS(index_exports);
 function vibra(initialValue) {
   let data = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
-  function subscribe(callback) {
+  function subscribe(callback, { callOnSubscribe = false } = {}) {
     subscribers.add(callback);
-    callback(data);
-    return () => {
-      subscribers.delete(callback);
-    };
+    if (callOnSubscribe) callback(data);
+    return () => subscribers.delete(callback);
   }
   function set(value) {
     if (data !== value) {
@@ -51,3 +50,16 @@ function vibra(initialValue) {
   };
 }
 var vibra_default = vibra;
+
+// src/vibra-error.ts
+var VibraError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VibraError";
+  }
+};
+var vibra_error_default = VibraError;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VibraError
+});

package/dist/index.mjs

@@ -2,12 +2,10 @@
 function vibra(initialValue) {
   let data = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
-  function subscribe(callback) {
+  function subscribe(callback, { callOnSubscribe = false } = {}) {
     subscribers.add(callback);
-    callback(data);
-    return () => {
-      subscribers.delete(callback);
-    };
+    if (callOnSubscribe) callback(data);
+    return () => subscribers.delete(callback);
   }
   function set(value) {
     if (data !== value) {
@@ -25,6 +23,16 @@ function vibra(initialValue) {
   };
 }
 var vibra_default = vibra;
+
+// src/vibra-error.ts
+var VibraError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VibraError";
+  }
+};
+var vibra_error_default = VibraError;
 export {
+  vibra_error_default as VibraError,
   vibra_default as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibra",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Vibra: A blazing fast, type-safe, and minimal state management library for TypeScript and JavaScript. Effortless reactivity, subscriptions, and memory safety in a tiny package.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",