Skip to content

Commit b617b0a

Browse files
EskiMojo14EskiMojo14
committed
added docs
1 parent 20b0066 commit b617b0a

File tree

22 files changed

+1040
-21
lines changed

22 files changed

+1040
-21
lines changed

‎library/src/methods/cache/cache.test-d.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@ import { describe, expectTypeOf, test } from 'vitest';
22
import type { StringIssue, StringSchema } from '../../schemas/index.ts';
33
import { string } from '../../schemas/index.ts';
44
import type {
5+
BaseCache,
56
InferInput,
67
InferIssue,
78
InferOutput,
89
OutputDataset,
910
} from '../../types/index.ts';
10-
import type { _Cache, BaseCache } from '../../utils/index.ts';
11+
import type { _Cache } from '../../utils/index.ts';
1112
import type { SchemaWithCache } from './cache.ts';
1213
import { cache } from './cache.ts';
1314

‎library/src/methods/cache/cache.ts

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ import type {
55
InferOutput,
66
OutputDataset,
77
} from '../../types/index.ts';
8-
import type { _CacheOptions } from '../../utils/index.ts';
8+
import type { CacheOptions } from '../../utils/index.ts';
99
import { _Cache, _getStandardProps } from '../../utils/index.ts';
1010
import type { CacheInstanceOptions } from './types.ts';
1111

1212
export type SchemaWithCache<
1313
TSchema extends BaseSchema<unknown, unknown, BaseIssue<unknown>>,
14-
TOptions extends _CacheOptions | CacheInstanceOptions<TSchema> | undefined,
14+
TOptions extends CacheOptions | CacheInstanceOptions<TSchema> | undefined,
1515
> = TSchema & {
1616
/**
1717
* The cache options.
@@ -47,7 +47,7 @@ export function cache<
4747
export function cache<
4848
const TSchema extends BaseSchema<unknown, unknown, BaseIssue<unknown>>,
4949
const TOptions extends
50-
| _CacheOptions
50+
| CacheOptions
5151
| CacheInstanceOptions<TSchema>
5252
| undefined,
5353
>(schema: TSchema, options: TOptions): SchemaWithCache<TSchema, TOptions>;
@@ -56,11 +56,11 @@ export function cache<
5656
export function cache(
5757
schema: BaseSchema<unknown, unknown, BaseIssue<unknown>>,
5858
options?:
59-
| _CacheOptions
59+
| CacheOptions
6060
| CacheInstanceOptions<BaseSchema<unknown, unknown, BaseIssue<unknown>>>
6161
): SchemaWithCache<
6262
BaseSchema<unknown, unknown, BaseIssue<unknown>>,
63-
| _CacheOptions
63+
| CacheOptions
6464
| CacheInstanceOptions<BaseSchema<unknown, unknown, BaseIssue<unknown>>>
6565
| undefined
6666
> {

‎library/src/methods/cache/cacheAsync.test-d.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@ import { describe, expectTypeOf, test } from 'vitest';
22
import type { StringIssue, StringSchema } from '../../schemas/index.ts';
33
import { string } from '../../schemas/index.ts';
44
import type {
5+
BaseCache,
56
InferInput,
67
InferIssue,
78
InferOutput,
89
OutputDataset,
910
} from '../../types/index.ts';
10-
import type { _Cache, BaseCache } from '../../utils/index.ts';
11+
import type { _Cache } from '../../utils/index.ts';
1112
import type { SchemaWithCacheAsync } from './cacheAsync.ts';
1213
import { cacheAsync } from './cacheAsync.ts';
1314

‎library/src/methods/cache/cacheAsync.ts

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ import type {
88
OutputDataset,
99
UnknownDataset,
1010
} from '../../types/index.ts';
11-
import type { _CacheOptions } from '../../utils/index.ts';
11+
import type { CacheOptions } from '../../utils/index.ts';
1212
import { _Cache, _getStandardProps } from '../../utils/index.ts';
1313
import type { CacheInstanceOptions } from './types.ts';
1414

1515
export type SchemaWithCacheAsync<
1616
TSchema extends
1717
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
1818
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>,
19-
TOptions extends _CacheOptions | CacheInstanceOptions<TSchema> | undefined,
19+
TOptions extends CacheOptions | CacheInstanceOptions<TSchema> | undefined,
2020
> = Omit<TSchema, 'async' | '~run'> & {
2121
/**
2222
* Whether it's async.
@@ -78,7 +78,7 @@ export function cacheAsync<
7878
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
7979
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>,
8080
const TOptions extends
81-
| _CacheOptions
81+
| CacheOptions
8282
| CacheInstanceOptions<TSchema>
8383
| undefined,
8484
>(schema: TSchema, options: TOptions): SchemaWithCacheAsync<TSchema, TOptions>;
@@ -89,15 +89,15 @@ export function cacheAsync(
8989
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
9090
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>,
9191
options?:
92-
| _CacheOptions
92+
| CacheOptions
9393
| CacheInstanceOptions<
9494
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
9595
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>
9696
>
9797
): SchemaWithCacheAsync<
9898
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
9999
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>,
100-
| _CacheOptions
100+
| CacheOptions
101101
| CacheInstanceOptions<
102102
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
103103
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>

‎library/src/methods/cache/types.ts

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,24 @@
11
import type { OutputDataset } from '../../types/dataset.ts';
22
import type {
3+
BaseCache,
34
BaseIssue,
45
BaseSchema,
56
BaseSchemaAsync,
67
InferIssue,
78
InferOutput,
89
} from '../../types/index.ts';
9-
import type { BaseCache } from '../../utils/index.ts';
1010

11+
/**
12+
* Cache instance options type.
13+
*/
1114
export interface CacheInstanceOptions<
1215
TSchema extends
1316
| BaseSchema<unknown, unknown, BaseIssue<unknown>>
1417
| BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>,
1518
> {
19+
/**
20+
* The cache instance.
21+
*/
1622
cache: BaseCache<
1723
unknown,
1824
OutputDataset<InferOutput<TSchema>, InferIssue<TSchema>>

‎library/src/types/other.ts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,11 @@ export type DefaultValue<
7070
? Awaited<ReturnType<TDefault>>
7171
: TDefault
7272
: never;
73+
74+
/**
75+
* A minimal cache interface, for custom cache implementations.
76+
*/
77+
export interface BaseCache<TKey, TValue> {
78+
get(key: TKey): TValue | undefined;
79+
set(key: TKey, value: TValue): void;
80+
}

‎library/src/utils/_Cache/_Cache.ts

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1+
import type { BaseCache } from '../../types/index.ts';
2+
13
/**
2-
* A minimal cache interface, for custom cache implementations.
4+
* Cache options.
35
*/
4-
export interface BaseCache<TKey, TValue> {
5-
get(key: TKey): TValue | undefined;
6-
set(key: TKey, value: TValue): void;
7-
}
8-
9-
export interface _CacheOptions {
6+
export interface CacheOptions {
107
maxSize?: number;
118
duration?: number;
129
}
@@ -23,7 +20,7 @@ export class _Cache<TKey, TValue> implements BaseCache<TKey, TValue> {
2320
private maxSize: number;
2421
private duration: number | undefined;
2522
private cache = new Map<TKey, _CacheEntry<TValue>>();
26-
constructor(options?: _CacheOptions) {
23+
constructor(options?: CacheOptions) {
2724
this.maxSize = options?.maxSize ?? 1;
2825
this.duration = options?.duration;
2926
}

‎website/src/routes/api/(async)/cacheAsync/index.mdx

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: cacheAsync
3+
description: Creates a version of a schema that caches its output.
4+
source: /methods/cache/cacheAsync.ts
5+
contributors:
6+
- EskiMojo14
7+
---
8+
9+
import { ApiList, Property } from '~/components';
10+
import { properties } from './properties';
11+
12+
# cacheAsync
13+
14+
Creates a version of a schema that caches its output.
15+
16+
```ts
17+
const Schema = v.cacheAsync<TSchema, TOptions>(schema, options);
18+
```
19+
20+
## Generics
21+
22+
- `TSchema` <Property {...properties.TSchema} />
23+
- `TOptions` <Property {...properties.TOptions} />
24+
25+
## Parameters
26+
27+
- `schema` <Property {...properties.schema} />
28+
- `options` <Property {...properties.options} />
29+
30+
### Explanation
31+
32+
The `cacheAsync` method creates a version of the given `schema` that caches its output. This can be useful for performance optimization, for example when validation involves a network request.
33+
34+
## Returns
35+
36+
- `Schema` <Property {...properties.Schema} />
37+
38+
## Examples
39+
40+
The following examples show how `cacheAsync` can be used.
41+
42+
### Cache schema
43+
44+
Schema that caches its output.
45+
46+
```ts
47+
const CacheSchema = v.cacheAsync(v.string());
48+
```
49+
50+
### Max size schema
51+
52+
Schema that caches its output for a maximum of 100 items.
53+
54+
```ts
55+
const MaxSizeSchema = v.cacheAsync(v.string(), { maxSize: 100 });
56+
```
57+
58+
### Max age schema
59+
60+
Schema that caches its output for a maximum of 10 seconds.
61+
62+
```ts
63+
const MaxAgeSchema = v.cacheAsync(v.string(), { duration: 10_000 });
64+
```
65+
66+
### Custom cache schema
67+
68+
Schema that uses a custom cache instance, in this case [QuickLRU](https://github.com/sindresorhus/quick-lru).
69+
70+
```ts
71+
import QuickLRU from 'quick-lru';
72+
73+
const CustomCacheSchema = v.cacheAsync(v.string(), {
74+
cache: new QuickLRU({ maxSize: 1000 }),
75+
});
76+
```
77+
78+
## Related
79+
80+
The following APIs can be combined with `cacheAsync`.
81+
82+
### Schemas
83+
84+
<ApiList
85+
items={[
86+
'any',
87+
'array',
88+
'bigint',
89+
'blob',
90+
'boolean',
91+
'custom',
92+
'date',
93+
'enum',
94+
'exactOptional',
95+
'file',
96+
'function',
97+
'instance',
98+
'intersect',
99+
'lazy',
100+
'literal',
101+
'looseObject',
102+
'looseTuple',
103+
'map',
104+
'nan',
105+
'never',
106+
'nonNullable',
107+
'nonNullish',
108+
'nonOptional',
109+
'null',
110+
'nullable',
111+
'nullish',
112+
'number',
113+
'object',
114+
'objectWithRest',
115+
'optional',
116+
'picklist',
117+
'promise',
118+
'record',
119+
'set',
120+
'strictObject',
121+
'strictTuple',
122+
'string',
123+
'symbol',
124+
'tuple',
125+
'tupleWithRest',
126+
'undefined',
127+
'undefinedable',
128+
'union',
129+
'unknown',
130+
'variant',
131+
'void',
132+
]}
133+
/>
134+
135+
### Methods
136+
137+
<ApiList items={['config', 'getDefault', 'getFallback']} />
138+
139+
### Actions
140+
141+
<ApiList items={['message', 'unwrap']} />
142+
143+
### Async
144+
145+
<ApiList items={['parseAsync', 'safeParseAsync']} />

0 commit comments

Comments
 (0)