Merge pull request #320 from chshanovskiy/main

Author: sergeysova

src/index.md

@@ -38,6 +38,7 @@ All methods split into categories.
 
 - [combineEvents](./combine-events/readme.md) — Wait for all passed events is triggered.
 - [format](./format/readme.md) — Combine stores to a string literal.
+- [readonly](./readonly/readme.md) — Create readonly version of store or event.
 - [reshape](./reshape/readme.md) — Destructure one store to different stores
 - [snapshot](./snapshot/readme.md) — Create store value snapshot.
 - [splitMap](./split-map/readme.md) — Split event to different events and map data.

src/readonly/index.ts

@@ -0,0 +1,20 @@
+import { Store, Event, is, combine } from 'effector';
+
+export function readonly<T extends unknown>(source: Store<T>): Store<T>;
+export function readonly<T extends unknown>(source: Event<T>): Event<T>;
+
+export function readonly<T extends unknown>(source: Store<T> | Event<T>) {
+  if (!is.targetable(source)) {
+    return source;
+  }
+
+  if (is.store(source)) {
+    return source.map((value) => value, { skipVoid: false });
+  }
+
+  if (is.event(source)) {
+    return source.map((value) => value);
+  }
+
+  return source;
+}

src/readonly/readme.md

@@ -0,0 +1,56 @@
+# readonly
+
+:::note since
+patronum 2.2.0
+:::
+
+```ts
+import { readonly } from 'patronum';
+// or
+import { readonly } from 'patronum/readonly';
+```
+
+### Motivation
+
+The method allows to convert writable store and callable event to their readonly versions.
+It can be helpful to create more strict public api.
+
+### Formulae
+
+```ts
+$result = readonly($store);
+```
+
+- `$result` store contains mapped `$store`, which is readonly for consumers.
+
+```ts
+result = readonly(event);
+```
+
+- `result` event contains mapped `event`, which is not callable by consumers.
+
+### Arguments
+
+- `value: Store<T>|Event<T>` — Any store or event, that required to be readonly
+
+### Returns
+
+- `result: Store<T>|Event<T>`
+
+Note: if passed argument is already derived, then argument returns as-is.
+
+### Example
+
+```ts
+const $store = createStore({});
+const $readonlyStore = readonly($store);
+
+console.assert(false === is.targetable($readonlyStore));
+```
+
+```ts
+const event = createEvent();
+const readonlyEvent = readonly(event);
+
+console.assert(false === is.targetable($readonlyStore));
+```

src/readonly/readonly.test.ts

@@ -0,0 +1,32 @@
+import { createEvent, createStore, is } from 'effector';
+import { readonly } from './index';
+
+it('should convert store to readonly store', () => {
+  const $store = createStore({});
+  const $result = readonly($store);
+
+  expect(is.targetable($result)).toBe(false);
+});
+
+it('should convert event to readonly event', () => {
+  const event = createEvent();
+  const result = readonly(event);
+
+  expect(is.targetable(result)).toBe(false);
+});
+
+it('should return store as-is if it is already derived', () => {
+  const $store = createStore({});
+  const $mapped = $store.map((state) => state);
+  const $result = readonly($mapped);
+
+  expect($result).toBe($mapped);
+});
+
+it('should return event as-is if it is already derived', () => {
+  const event = createEvent();
+  const mapped = event.map((value) => value);
+  const result = readonly(mapped);
+
+  expect(result).toBe(mapped);
+});

test-typings/readonly.ts

@@ -0,0 +1,51 @@
+import { createDomain, createEffect, createEvent, createStore, Store, Event } from 'effector';
+import { expectType } from 'tsd';
+import { readonly } from '../dist/readonly';
+
+// Always returns the store
+{
+  const $store = createStore<number>(1);
+
+  expectType<Store<number>>(readonly($store));
+}
+
+// Always returns the store
+{
+  const $store = createStore<number>(1);
+  const $mapped = $store.map(store => store)
+
+  expectType<Store<number>>(readonly($mapped));
+}
+
+// Always returns the event
+{
+  const event = createEvent<void>();
+
+  expectType<Event<void>>(readonly(event));
+}
+
+// Always returns the event
+{
+  const event = createEvent<void>();
+  const mapped = event.map(event => event)
+
+  expectType<Event<void>>(readonly(mapped));
+}
+
+// Should not receive non-store or non-event as argument
+{
+  // @ts-expect-error
+  readonly(createEffect());
+  
+  // @ts-expect-error
+  readonly(createDomain());
+
+  // @ts-expect-error
+  readonly(1);
+
+  // @ts-expect-error
+  readonly(true);
+
+  // @ts-expect-error
+  readonly({});
+}