Mirroristas/gun
2
0
Fork 0
mirror of https://github.com/amark/gun.git synced 2025-03-30 15:08:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: update types for better extendable

Browse Source
This commit is contained in:
bluelovers 2020-02-05 08:37:00 +08:00
parent 248e09c573
commit c93149a3a0
10 changed files with 50 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -14,3 +14,4 @@ yarn.lock
/types/*.ts
!/types/*.d.ts
/gun.ts
/temp/

1
.npmignore
View File

@ -1 +1,2 @@
*.ts
/temp/

4
global.d.ts vendored Normal file
View File

@ -0,0 +1,4 @@
import { IGunStatic } from './types/static';
declare global {
var Gun: IGunStatic;
}

6
gun.d.ts vendored
View File

@ -1,3 +1,3 @@
import { Constructor } from './types/static';
declare const cons: Constructor;
export = cons;
import { IGunStatic } from './types/static';
declare const Gun: IGunStatic;
export = Gun;

3
index.d.ts vendored Normal file
View File

@ -0,0 +1,3 @@
import { IGunStatic } from './types/static';
declare const Gun: IGunStatic;
export = Gun;

1
package.json
View File

@ -2,6 +2,7 @@
"name": "gun",
"version": "0.2020.116",
"description": "A realtime, decentralized, offline-first, graph data synchronization engine.",
"types": "index.d.ts",
"main": "index.js",
"browser": "browser.js",
"ios": "browser.ios.js",

48
types/chain.d.ts vendored
View File

@ -1,6 +1,6 @@
import { AlwaysDisallowedType, DisallowPrimitives, DisallowArray, AckCallback, ArrayOf, ArrayAsRecord, Saveable } from './types';
import { ConstructorOptions } from './options';
export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extends 'pre_root' | 'root' | false = false> {
import { IGunConstructorOptions } from './options';
export interface IGunChainReference<DataType = Record<string, any>, ReferenceKey = any, IsTop extends 'pre_root' | 'root' | false = false> {
/**
* Save data into gun, syncing it with your connected peers.
*
@ -14,7 +14,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
*
* @param callback invoked on each acknowledgment
*/
put(data: Partial<AlwaysDisallowedType<DisallowPrimitives<IsTop, DisallowArray<DataType>>>>, callback?: AckCallback): ChainReference<DataType, ReferenceKey, IsTop>;
put(data: Partial<AlwaysDisallowedType<DisallowPrimitives<IsTop, DisallowArray<DataType>>>>, callback?: AckCallback): IGunChainReference<DataType, ReferenceKey, IsTop>;
/**
* Where to read data from.
* @param key The key is the ID or property name of the data that you saved from earlier
@ -27,11 +27,11 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
*
* **Here the type of callback respect to the actual behavior**
*/
get<K extends keyof DataType>(key: ArrayOf<DataType> extends never ? K : never, callback?: (
get<K extends keyof DataType>(key: ArrayOf<DataType> extends never ? K : ArrayOf<DataType>, callback?: (
/** the raw data. Internal node of gun. Will not typed here. */
paramA: Record<'gun' | '$' | 'root' | 'id' | 'back' | 'on' | 'tag' | 'get' | 'soul' | 'ack' | 'put', any>,
/** the key, ID, or property name of the data. */
paramB: Record<'off' | 'to' | 'next' | 'the' | 'on' | 'as' | 'back' | 'rid' | 'id', any>) => void): ChainReference<DataType[K], K, IsTop extends 'pre_root' ? 'root' : false>;
paramB: Record<'off' | 'to' | 'next' | 'the' | 'on' | 'as' | 'back' | 'rid' | 'id', any>) => void): IGunChainReference<DataType[K], K, IsTop extends 'pre_root' ? 'root' : false>;
/**
* Change the configuration of the gun database instance.
* @param options The options argument is the same object you pass to the constructor.
@ -39,7 +39,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
* The options's properties replace those in the instance's configuration but options.peers are **added** to peers known to the gun instance.
* @returns No mention in the document, behavior as `ChainReference<DataType, ReferenceKey>`
*/
opt(options: ConstructorOptions): ChainReference<DataType, ReferenceKey>;
opt(options: IGunConstructorOptions): IGunChainReference<DataType, ReferenceKey>;
/**
* Move up to the parent context on the chain.
*
@ -48,7 +48,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
* `-1` or `Infinity` will take you to the root.
* @returns Impossible to determinate final type. You must cast it by yourself.
*/
back(amount?: number): ChainReference;
back(amount?: number): IGunChainReference;
/**
* Subscribe to updates and changes on a node or property in realtime.
* @param option Currently, the only option is to filter out old data, and just be given the changes.
@ -62,14 +62,14 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
*/
on(callback: (data: DisallowPrimitives<IsTop, AlwaysDisallowedType<ArrayAsRecord<DataType>>>, key: ReferenceKey) => void, option?: {
change: boolean;
} | boolean): ChainReference<DataType, ReferenceKey>;
} | boolean): IGunChainReference<DataType, ReferenceKey>;
/**
* Get the current data without subscribing to updates. Or `undefined` if it cannot be found.
* @returns In the document, it said the return value may change in the future. Don't rely on it.
*/
once(callback?: (data: (DisallowPrimitives<IsTop, AlwaysDisallowedType<ArrayAsRecord<DataType>>>) | undefined, key: ReferenceKey) => void, option?: {
wait: number;
}): ChainReference<DataType, ReferenceKey>;
}): IGunChainReference<DataType, ReferenceKey>;
/**
* **.set does not means 'set data', it means a Mathematical Set**
*
@ -82,13 +82,13 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
set(data: AlwaysDisallowedType<DataType extends Array<infer U> ? U extends {
[key: string]: any;
[key: number]: any;
} ? ArrayOf<DataType> : never : never>, callback?: AckCallback): ChainReference<ArrayOf<DataType>>;
} ? ArrayOf<DataType> : never : never>, callback?: AckCallback): IGunChainReference<ArrayOf<DataType>>;
/**
* Map iterates over each property and item on a node, passing it down the chain,
* behaving like a forEach on your data.
* It also subscribes to every item as well and listens for newly inserted items.
*/
map(callback?: (value: ArrayOf<DataType>, key: DataType) => ArrayOf<DataType> | undefined): ChainReference<ArrayOf<DataType>, ReferenceKey>;
map(callback?: (value: ArrayOf<DataType>, key: DataType) => ArrayOf<DataType> | undefined): IGunChainReference<ArrayOf<DataType>, ReferenceKey>;
/**
* Undocumented, but extremely useful and mentioned in the document
*
@ -105,14 +105,14 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
* **Warning**: Not included by default! You must include it yourself via `require('gun/lib/path.js')` or
* `<script src="https://cdn.jsdelivr.net/npm/gun/lib/path.js"></script>`!
*/
path?(path: string | string[]): ChainReference;
path?(path: string | string[]): IGunChainReference;
/**
* Handle cases where data can't be found.
*
* **Warning**: Not included by default! You must include it yourself via `require('gun/lib/not.js')` or
* `<script src="https://cdn.jsdelivr.net/npm/gun/lib/not.js"></script>`!
*/
not?(callback: (key: ReferenceKey) => void): ChainReference<DataType, ReferenceKey>;
not?(callback: (key: ReferenceKey) => void): IGunChainReference<DataType, ReferenceKey>;
/**
* Open behaves very similarly to gun.on, except it gives you the **full depth of a document** on every update.
* It also works with graphs, tables, or other data structures. Think of it as opening up a live connection to a document.
@ -120,14 +120,14 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
* **Warning**: Not included by default! You must include it yourself via `require('gun/lib/open.js')` or
* `<script src="https://cdn.jsdelivr.net/npm/gun/lib/open.js"></script>`!
*/
open?(callback: (data: ArrayAsRecord<DataType>) => void): ChainReference<DataType, ReferenceKey>;
open?(callback: (data: ArrayAsRecord<DataType>) => void): IGunChainReference<DataType, ReferenceKey>;
/**
* Loads the full object once. It is the same as `open` but with the behavior of `once`.
*
* **Warning**: Not included by default! You must include it yourself via `require('gun/lib/load.js')` or
* `<script src="https://cdn.jsdelivr.net/npm/gun/lib/load.js"></script>`!
*/
load?(callback: (data: ArrayAsRecord<DataType>) => void): ChainReference<DataType, ReferenceKey>;
load?(callback: (data: ArrayAsRecord<DataType>) => void): IGunChainReference<DataType, ReferenceKey>;
/**
* Returns a promise for you to use.
*
@ -144,7 +144,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
promise?<TResult1 = {
put: ArrayAsRecord<DataType>;
key: ReferenceKey;
gun: ChainReference<DataType, ReferenceKey>;
gun: IGunChainReference<DataType, ReferenceKey>;
}>(onfulfilled?: (value: TResult1) => TResult1 | PromiseLike<TResult1>): Promise<TResult1>;
/**
* bye lets you change data after that browser peer disconnects.
@ -164,20 +164,20 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
* **Warning**: Not included by default! You must include it yourself via `require('gun/lib/later.js')` or
* `<script src="https://cdn.jsdelivr.net/npm/gun/lib/later.js"></script>`!
*/
later?(callback: (this: ChainReference<DataType, ReferenceKey>, data: ArrayAsRecord<DataType>, key: ReferenceKey) => void, seconds: number): ChainReference<DataType, ReferenceKey>;
later?(callback: (this: IGunChainReference<DataType, ReferenceKey>, data: ArrayAsRecord<DataType>, key: ReferenceKey) => void, seconds: number): IGunChainReference<DataType, ReferenceKey>;
/**
* After you save some data in an unordered list, you may need to remove it.
*
* **Warning**: Not included by default! You must include it yourself via `require('gun/lib/unset.js')` or
* `<script src="https://cdn.jsdelivr.net/npm/gun/lib/unset.js"></script>`!
*/
unset?(data: ArrayOf<DataType>): ChainReference<DataType, ReferenceKey>;
unset?(data: ArrayOf<DataType>): IGunChainReference<DataType, ReferenceKey>;
/**
* Subscribes to all future events that occur on the Timegraph and retrieve a specified number of old events
*
* **Warning**: The Timegraph extension isn't required by default, you would need to include at "gun/lib/time.js"
*/
time?(callback: (data: ArrayOf<DataType>, key: ReferenceKey, time: number) => void, alsoReceiveNOldEvents?: number): ChainReference<DataType, ReferenceKey>;
time?(callback: (data: ArrayOf<DataType>, key: ReferenceKey, time: number) => void, alsoReceiveNOldEvents?: number): IGunChainReference<DataType, ReferenceKey>;
/** Pushes data to a Timegraph with it's time set to Gun.state()'s time */
time?(data: ArrayOf<DataType>): void;
/**
@ -192,7 +192,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
pub: string;
} | {
err: string;
}) => void, opt?: {}): ChainReference;
}) => void, opt?: {}): IGunChainReference;
/**
* Authenticates a user, previously created via User.create.
* @param alias Username or Alias which can be used to find a user.
@ -214,7 +214,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
soul: string;
} | {
err: string;
}) => void, opt?: {}): ChainReference;
}) => void, opt?: {}): IGunChainReference;
/**
* Returns the key pair in the form of an object as below.
*/
@ -224,7 +224,7 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
* @param opt unused in current implementation.
* @param cb unused in current implementation.
*/
leave(opt?: never, cb?: never): ChainReference;
leave(opt?: never, cb?: never): IGunChainReference;
/**
* Deletes a user from the current gun instance and propagates the delete to other peers.
* @param alias Username or alias.
@ -241,9 +241,9 @@ export interface ChainReference<DataType = any, ReferenceKey = any, IsTop extend
*/
recall(opt?: {
sessionStorage: boolean;
}, cb?: Parameters<ChainReference['auth']>[2]): ChainReference;
}, cb?: Parameters<IGunChainReference['auth']>[2]): IGunChainReference;
/**
* @param publicKey If you know a users publicKey you can get their user graph and see any unencrypted data they may have stored there.
*/
user(publicKey?: string): ChainReference;
user(publicKey?: string): IGunChainReference;
}

7
types/options.d.ts vendored
View File

@ -3,7 +3,7 @@
* Their project README will likely list the exposed options
* https://github.com/amark/gun/wiki/Modules
*/
export declare type ConstructorOptions = Partial<{
export interface IGunConstructorOptions extends Partial<{
/** Undocumented but mentioned. Write data to a JSON. */
file: string;
/** Undocumented but mentioned. Create a websocket server */
@ -15,7 +15,7 @@ export declare type ConstructorOptions = Partial<{
bucket: any;
};
/** the URLs are properties, and the value is an empty object. */
peers: Record<string, {}>;
peers: string[] | Record<string, {}>;
/** default: true, creates and persists local (nodejs) data using Radisk. */
radisk: boolean;
/** default: true, persists local (browser) data to localStorage. */
@ -27,4 +27,5 @@ export declare type ConstructorOptions = Partial<{
* @see https://github.com/amark/gun/wiki/Modules
*/
[key: string]: any;
}>;
}> {
}

14
types/static.d.ts vendored
View File

@ -1,6 +1,6 @@
import { ChainReference } from './chain';
import { ConstructorOptions } from './options';
export interface Constructor {
import { IGunChainReference } from './chain';
import { IGunConstructorOptions } from './options';
export interface IGunStatic {
/**
* @description
* no parameters creates a local datastore using the default persistence layer, either localStorage or Radisk.
@ -9,17 +9,17 @@ export interface Constructor {
*
* or you can pass in an array of URLs to sync with multiple peers.
*/
<DataType = any>(options?: string | string[] | ConstructorOptions): ChainReference<DataType, any, 'pre_root'>;
new <DataType = any>(options?: string | string[] | ConstructorOptions): ChainReference<DataType, any, 'pre_root'>;
<DataType = any>(options?: string | string[] | IGunConstructorOptions): IGunChainReference<DataType, any, 'pre_root'>;
new <DataType = any>(options?: string | string[] | IGunConstructorOptions): IGunChainReference<DataType, any, 'pre_root'>;
node: {
/** Returns true if data is a gun node, otherwise false. */
is(anything: any): anything is ChainReference;
is(anything: any): anything is IGunChainReference;
/**
* Returns data's gun ID (instead of manually grabbing its metadata i.e. data["_"]["#"], which is faster but could change in the future)
*
* Returns undefined if data is not correct gun data.
*/
soul(data: ChainReference): string;
soul(data: IGunChainReference): string;
/** Returns a "gun-ified" variant of the json input by injecting a new gun ID into the metadata field. */
ify(json: any): any;
};

5
types/types.d.ts vendored
View File

@ -1,4 +1,4 @@
import { ChainReference } from './chain';
import { IGunChainReference } from './chain';
export declare type ArrayOf<T> = T extends Array<infer U> ? U : never;
/** Gun does not accept Array value, so we need extract to make types correct */
export declare type AllowArray<T> = ArrayOf<T> extends never ? T : ArrayOf<T>;
@ -13,7 +13,7 @@ export declare type AccessObject<T> = T extends object ? {
/** These types cannot be stored on Gun's root level */
export declare type DisallowPrimitives<Open, T> = Open extends false ? T : T extends string ? never : T extends number ? never : T extends boolean ? never : T extends null ? never : T extends undefined ? never : T;
export declare type ArrayAsRecord<DataType> = ArrayOf<DataType> extends never ? DataType : Record<string, any>;
export declare type Saveable<DataType> = Partial<DataType> | string | number | boolean | null | ChainReference<DataType>;
export declare type Saveable<DataType> = Partial<DataType> | string | number | boolean | null | IGunChainReference<DataType>;
export declare type AckCallback = (ack: {
err: Error;
ok: any;
@ -21,5 +21,4 @@ export declare type AckCallback = (ack: {
err: undefined;
ok: string;
}) => void;
export declare type Parameters<T extends (...args: any[]) => any> = T extends (...args: infer P) => any ? P : never;
export declare type CryptoKeyPair = Record<'pub' | 'priv' | 'epub' | 'epriv', string>;