docs(readme): update usage to add more example

TomokiMiyauci · Jun 18, 2023 · d757520 · d757520
1 parent 399f65c
commit d757520
Showing 1 changed file with 57 additions and 127 deletions.
diff --git a/README.md b/README.md
@@ -19,164 +19,78 @@ implementation. This can be used as a cache for TC39
 
 ## Usage
 
-### FIFO
+All Map-like constructors specify capacity.
 
-FIFO(First In, First Out) implementations.
-
-#### FIFOMap
-
-When the upper limit is reached, replaces the entry with FIFO algorithm.
-
-```ts
-import { FIFOMap } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
-
-declare const maxNumOfEntries: number;
-const map = new FIFOMap(maxNumOfEntries);
-```
-
-#### FIFOSet
-
-When the upper limit is reached, replaces the value with FIFO algorithm.
-
-```ts
-import { FIFOSet } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
-
-declare const maxNumOfValues: number;
-const set = new FIFOSet(maxNumOfValues);
-```
-
-### LIFO
-
-LIFO(Last In, First Out) implementations.
-
-#### LIFOMap
-
-When the upper limit is reached, replaces the entry with LIFO algorithm.
-
-```ts
-import { LIFOMap } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
-
-declare const maxNumOfEntries: number;
-const map = new LIFOMap(maxNumOfEntries);
-```
-
-#### LIFOSet
-
-When the upper limit is reached, replaces the value with LIFO algorithm.
-
-```ts
-import { LIFOSet } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
-
-declare const maxNumOfValues: number;
-const set = new LIFOSet(maxNumOfValues);
-```
-
-### LRU
-
-LRU(Least Recently Used) implementations.
-
-#### LRUMap
-
-When the upper limit is reached, replaces the entry with LRU algorithm.
+When the limit is reached, the cache is adjusted according to the cache
+replacement policy.
 
 ```ts
 import { LRUMap } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
+import { assert, assertEquals } from "https://deno.land/std/testing/asserts.ts";
 
-declare const maxNumOfEntries: number;
-const map = new LRUMap(maxNumOfEntries);
-```
-
-#### LRUSet
-
-When the upper limit is reached, replaces the value with LRU algorithm.
+declare const capacity: 2;
 
-```ts
-import { LRUSet } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
+const map = new LRUMap<number, string>(capacity);
 
-declare const maxNumOfValues: number;
-const set = new LRUSet(maxNumOfValues);
-```
+map.set(200, "Ok");
+map.set(201, "Created");
 
-### LFU
+assertEquals(map.size, 2);
 
-LFU(Least Frequently Used) implementations.
+map.set(202, "Accepted");
 
-#### LFUMap
+assertEquals(map.size, 2);
+assert(map.has(201));
+assert(map.has(202));
+```
 
-When the upper limit is reached, replaces the entry with LFU algorithm.
+It provides a Map-like constructor with the following cache-replacement-policy:
 
-```ts
-import { LFUMap } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
+- [FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))
+- [LIFO](https://en.wikipedia.org/wiki/LIFO)
+- [LRU](https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU)
+- [LFU](https://en.wikipedia.org/wiki/Least_frequently_used)
 
-declare const maxNumOfEntries: number;
-const map = new LFUMap(maxNumOfEntries);
-```
+### Set like
 
-#### LFUSet
+`SetLike` is a set-like constructor, with the same cache-replacement-policy.
 
-When the upper limit is reached, replaces the value with LFU algorithm.
+`LFUSet` preferentially removes item with fewer references (by `has` or `add`).
 
 ```ts
 import { LFUSet } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
+import { assert, assertEquals } from "https://deno.land/std/testing/asserts.ts";
 
-declare const maxNumOfValues: number;
-const set = new LFUSet(maxNumOfValues);
-```
+declare const capacity: 2;
 
-## Common
+const set = new LFUSet<number>(capacity);
 
-List items common to all implementations.
+set.add(200);
+set.add(201);
 
-### Interface
+assertEquals(set.size, 2);
+assert(set.has(200));
 
-All instance have following members.
-
-MapLike:
-
-```ts
-interface MapLike<K, V> {
-  /** The number of entries. */
-  size: number;
+set.add(202);
 
-  /** Whether has an entry with the given {@link key}. */
-  has: (key: K) => boolean;
-
-  /** Returns the value of the entry with the given {@link key}, if any such entry exists; otherwise returns `undefined`. */
-  get: (key: K) => V | undefined;
-
-  /** Adds an entry with the given {@link key} mapped to the given {@link value}. */
-  set: (key: K, value: V) => this;
-
-  /** Deletes the entry with the given {@link key}. */
-  delete: (key: K) => boolean;
-
-  /** Removes all entries. */
-  clear: () => void;
-}
+assert(set.has(200));
+assert(set.has(202));
 ```
 
-SetLike:
-
-```ts
-interface SetLike<T> {
-  /** The number of values. */
-  size: number;
-
-  /** Whether has the given {@link value}. */
-  has: (value: T) => boolean;
+### Initial value
 
-  /** Adds the given {@link value}. */
-  add: (value: T) => this;
+Accepts an initial value, like `Map` or `Set`. If overcapacity occurs, the cache
+is adjusted according to the policy.
 
-  /** Deletes the given {@link value}. */
-  delete: (value: T) => boolean;
+```ts
+import { FIFOSet } from "https://deno.land/x/cache_mapset@$VERSION/mod.ts";
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 
-  /** Removes all values. */
-  clear: () => void;
-}
+const set = new FIFOSet<number>(3, [0, 1, 2, 3, 4, 5]);
+assertEquals(set.size, 3);
 ```
 
-### Throwing error
+### Errors
 
 All constructors specify a capacity as their first argument.
 
@@ -189,6 +103,22 @@ import { assertThrows } from "https://deno.land/std/testing/asserts.ts";
 assertThrows(() => new FIFOMap(-1));
 ```
 
+### Difference from Map and Set
+
+`MapLike` and `SetLike` are not `Iterable`.
+
+The following members are not implemented.
+
+- `Symbol.iterator`
+- `forEach`
+- `entries`
+- `keys`
+- `values`
+
+Currently, these are outside the scope of the specification. For more
+information, check
+[Data iteration and order](https://github.com/tc39/proposal-policy-map-set/issues/3).
+
 ## API
 
 See [deno doc](https://deno.land/x/cache_mapset?doc) for all APIs.