Merge branch 'master' into manhattan

.gitignore

@@ -14,3 +14,7 @@ isolate*.log
 .esm-cache
 .sessionStorage
 .localStorage
+/types/**/*.ts
+!/types/**/*.d.ts
+/gun.ts
+/temp/

.npmignore

@@ -0,0 +1,3 @@
+*.ts
+/temp/
+!*.d.ts

global.d.ts

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

gun.d.ts

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

index.d.ts

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

lib/then.js

@@ -11,11 +11,12 @@ Gun.chain.promise = function(cb) {
 };
 
 // Returns a promise for the data, key of the gun call
-Gun.chain.then = function() {
+Gun.chain.then = function(cb) {
 	var gun = this;
-  return (new Promise((res, rej)=>{
+  var p = (new Promise((res, rej)=>{
     gun.once(function (data, key) {
       res(data, key); //call resolve when data is returned
     })
   }))
+  return cb ? p.then(cb) : p;
 };

package.json

@@ -2,6 +2,7 @@
   "name": "gun",
   "version": "0.2020.301",
   "description": "A realtime, decentralized, offline-first, graph data synchronization engine.",
+  "types": "index.d.ts",
   "main": "index.js",
   "browser": "browser.js",
   "ios": "browser.ios.js",
@@ -59,18 +60,24 @@
     "ws": "^7.2.1"
   },
   "optionalDependencies": {
-    "text-encoding": "^0.7.0",
+    "emailjs": "^2.2.0",
     "isomorphic-webcrypto": "^2.3.2",
     "bufferutil": "^4.0.1",
     "utf-8-validate": "^5.0.2",
-    "emailjs": "^2.2.0"
+    "text-encoding": "^0.7.0"
   },
   "devDependencies": {
+    "@types/ip": "^1.1.0",
+    "@types/mocha": "^7.0.1",
+    "@types/node": "^13.7.0",
+    "@types/uglify-js": "^3.0.4",
+    "@types/ws": "^7.2.1",
     "aws-sdk": "^2.528.0",
     "ip": "^1.1.5",
     "mocha": "^6.2.0",
     "panic-manager": "^1.2.0",
     "panic-server": "^1.1.1",
+    "ts-type": "^1.2.13",
     "uglify-js": "^3.6.0"
   }
 }

tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "declaration": true
+  }
+}

types/chain.d.ts

@@ -0,0 +1,256 @@
+import { AlwaysDisallowedType, DisallowPrimitives, DisallowArray, AckCallback, ArrayOf, ArrayAsRecord, Saveable, IGunCryptoKeyPair } from './types';
+import { IGunConstructorOptions } from './options';
+import { ITSResolvable } from 'ts-type';
+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.
+     *
+     * * You cannot save primitive values at the root level.
+     *
+     * @param data You do not need to re-save the entire object every time,
+     * gun will automatically merge your data into what already exists as a "partial" update.
+     *
+     * * `undefined`, `NaN`, `Infinity`, `array`, will be rejected.
+     * * Traditional arrays are dangerous in real-time apps. Use `gun.set` instead.
+     *
+     * @param callback invoked on each acknowledgment
+     */
+    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
+     *  (or that will be saved later).
+     * * Note that if you use .put at any depth after a get it first reads the data and then writes, merging the data as a partial update.
+     * @param callback You will usually be using gun.on or gun.once to actually retrieve your data,
+     * not this callback (it is intended for more low level control, for module and extensions).
+     *
+     * **Avoid use callback. The type in the document may be wrong.**
+     *
+     * **Here the type of callback respect to the actual behavior**
+     */
+    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): 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.
+     *
+     * 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: IGunConstructorOptions): IGunChainReference<DataType, ReferenceKey>;
+    /**
+     * Move up to the parent context on the chain.
+     *
+     * Every time a new chain is created, a reference to the old context is kept to go back to.
+     * @param amount The number of times you want to go back up the chain.
+     * `-1` or `Infinity` will take you to the root.
+     * @returns Impossible to determinate final type. You must cast it by yourself.
+     */
+    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.
+     * If you're listening to a node with 100 fields, and just one changes,
+     * you'll instead be passed a node with a single property representing that change rather than the full node every time.
+     * @param callback
+     * Once initially and whenever the property or node you're focused on changes, this callback is immediately fired with the data as it is at that point in time.
+     *
+     * Since gun streams data, the callback will probably be called multiple times as new chunk comes in.
+     * To remove a listener call .off() on the same property or node.
+     */
+    on(callback: (data: DisallowPrimitives<IsTop, AlwaysDisallowedType<ArrayAsRecord<DataType>>>, key: ReferenceKey) => void, option?: {
+        change: boolean;
+    } | 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;
+    }): IGunChainReference<DataType, ReferenceKey>;
+    /**
+     * **.set does not means 'set data', it means a Mathematical Set**
+     *
+     * Add a unique item to an unordered list.
+     * `gun.set` works like a mathematical set, where each item in the list is unique.
+     * If the item is added twice, it will be merged.
+     *
+     * **This means only objects, for now, are supported.**
+     */
+    set(data: AlwaysDisallowedType<DataType extends Array<infer U> ? U extends {
+        [key: string]: any;
+        [key: number]: any;
+    } ? 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): IGunChainReference<ArrayOf<DataType>, ReferenceKey>;
+    /**
+     * Undocumented, but extremely useful and mentioned in the document
+     *
+     * Remove **all** listener on this node.
+     */
+    off(): void;
+    /**
+     *
+     * Path does the same thing as `.get` but has some conveniences built in.
+     * @deprecated This is not friendly with type system.
+     *
+     * **Warning**: This extension was removed from core, you probably shouldn't be using it!
+     *
+     * **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[]): 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): 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.
+     *
+     * **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): 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): IGunChainReference<DataType, ReferenceKey>;
+    /**
+     * Returns a promise for you to use.
+     *
+     * **Warning**: Not included by default! You must include it yourself via `require('gun/lib/then.js')` or
+     * `<script src="https://cdn.jsdelivr.net/npm/gun/lib/then.js"></script>`!
+     */
+    then?<R, TResult1 = ArrayAsRecord<DataType>>(onfulfilled: (value: TResult1) => ITSResolvable<R>): Promise<R>;
+    then?<TResult1 = ArrayAsRecord<DataType>>(): Promise<TResult1>;
+    /**
+     * Returns a promise for you to use.
+     *
+     * **Warning**: Not included by default! You must include it yourself via `require('gun/lib/then.js')` or
+     *  `<script src="https://cdn.jsdelivr.net/npm/gun/lib/then.js"></script>`!
+     */
+    promise?<R, TResult1 = {
+        put: ArrayAsRecord<DataType>;
+        key: ReferenceKey;
+        gun: IGunChainReference<DataType, ReferenceKey>;
+    }>(onfulfilled: (value: TResult1) => ITSResolvable<R>): Promise<R>;
+    promise?<TResult1 = {
+        put: ArrayAsRecord<DataType>;
+        key: ReferenceKey;
+        gun: IGunChainReference<DataType, ReferenceKey>;
+    }>(): Promise<TResult1>;
+    /**
+     * bye lets you change data after that browser peer disconnects.
+     * This is useful for games and status messages,
+     * that if a player leaves you can remove them from the game or set a user's status to "away".
+     *
+     * **Warning**: Not included by default! You must include it yourself via `require('gun/lib/bye.js')` or
+     * `<script src="https://cdn.jsdelivr.net/npm/gun/lib/bye.js"></script>`!
+     */
+    bye?(): {
+        put(data: DisallowArray<Saveable<DataType>>): void;
+    };
+    /**
+     * Say you save some data, but want to do something with it later, like expire it or refresh it.
+     * Well, then `later` is for you! You could use this to easily implement a TTL or similar behavior.
+     *
+     * **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: 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>): 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): IGunChainReference<DataType, ReferenceKey>;
+    /** Pushes data to a Timegraph with it's time set to Gun.state()'s time */
+    time?(data: ArrayOf<DataType>): void;
+    /**
+     * Creates a new user and calls callback upon completion.
+     * @param alias Username or Alias which can be used to find a user.
+     * @param pass Passphrase that will be extended with PBKDF2 to make it a secure way to login.
+     * @param cb Callback that is to be called upon creation of the user.
+     * @param opt Option Object containing options for creation. (In gun options are added at end of syntax. opt is rarely used, hence is added at the end.)
+     */
+    create(alias: string, pass: string, cb?: (ack: {
+        ok: 0;
+        pub: string;
+    } | {
+        err: string;
+    }) => void, opt?: {}): IGunChainReference;
+    /**
+     * Authenticates a user, previously created via User.create.
+     * @param alias Username or Alias which can be used to find a user.
+     * @param pass Passphrase for the user
+     * @param cb Callback that is to be called upon authentication of the user.
+     * @param opt Option Object containing options for authentiaction. (In gun options are added at end of syntax. opt is rarely used, hence is added at the end.)
+     */
+    auth(alias: string, pass: string, cb?: (ack: {
+        ack: 2;
+        get: string;
+        on: (...args: [unknown, unknown, unknown]) => unknown;
+        put: {
+            alias: string;
+            auth: any;
+            epub: string;
+            pub: string;
+        };
+        sea: IGunCryptoKeyPair;
+        soul: string;
+    } | {
+        err: string;
+    }) => void, opt?: {}): IGunChainReference;
+    /**
+     * Returns the key pair in the form of an object as below.
+     */
+    pair(): IGunCryptoKeyPair;
+    /**
+     * Log out currently authenticated user. Parameters are unused in the current implementation.
+     * @param opt unused in current implementation.
+     * @param cb unused in current implementation.
+     */
+    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.
+     * @param pass Passphrase for the user.
+     * @param cb Callback that is called when the user was successfully deleted.
+     */
+    delete(alias: string, pass: string, cb?: (ack: {
+        ok: 0;
+    }) => void): Promise<void>;
+    /**
+     * Recall saves a users credentials in sessionStorage of the browser. As long as the tab of your app is not closed the user stays logged in, even through page refreshes and reloads.
+     * @param opt option object If you want to use browser sessionStorage to allow users to stay logged in as long as the session is open, set opt.sessionStorage to true
+     * @param cb internally the callback is passed on to the user.auth function to logged the user back in. Refer to user.auth for callback documentation.
+     */
+    recall(opt?: {
+        sessionStorage: boolean;
+    }, 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): IGunChainReference;
+}

types/options.d.ts

@@ -0,0 +1,31 @@
+/**
+ * options['module name'] allows you to pass options to a 3rd party module.
+ * Their project README will likely list the exposed options
+ * https://github.com/amark/gun/wiki/Modules
+ */
+export interface IGunConstructorOptions extends Partial<{
+    /** Undocumented but mentioned. Write data to a JSON. */
+    file: string;
+    /** Undocumented but mentioned. Create a websocket server */
+    web: any;
+    /** Undocumented but mentioned. Amazon S3 */
+    s3: {
+        key: any;
+        secret: any;
+        bucket: any;
+    };
+    /** the URLs are properties, and the value is an empty object. */
+    peers: string[] | Record<string, {}>;
+    /** default: true, creates and persists local (nodejs) data using Radisk. */
+    radisk: boolean;
+    /** default: true, persists local (browser) data to localStorage. */
+    localStorage: boolean;
+    /** uuid allows you to override the default 24 random alphanumeric soul generator with your own function. */
+    uuid(): string;
+    /**
+     * allows you to pass options to a 3rd party module. Their project README will likely list the exposed options
+     * @see https://github.com/amark/gun/wiki/Modules
+     */
+    [key: string]: any;
+}> {
+}

types/static.d.ts

@@ -0,0 +1,26 @@
+import { IGunChainReference } from './chain';
+import { IGunConstructorOptions } from './options';
+import { IGunStaticNode } from './static/node';
+import { IGunStaticSEA } from './static/sea';
+export interface IGunStatic {
+    /**
+     * @description
+     * no parameters creates a local datastore using the default persistence layer, either localStorage or Radisk.
+     * @param options
+     * passing a URL creates the above local datastore that also tries to sync with the URL.
+     *
+     * or you can pass in an array of URLs to sync with multiple peers.
+     */
+    <DataType = any>(options?: string | string[] | IGunConstructorOptions): IGunChainReference<DataType, any, 'pre_root'>;
+    new <DataType = any>(options?: string | string[] | IGunConstructorOptions): IGunChainReference<DataType, any, 'pre_root'>;
+    readonly node: IGunStaticNode;
+    /** @see https://gun.eco/docs/SEA */
+    readonly SEA: IGunStaticSEA;
+    readonly version: string;
+    readonly chain: IGunChainReference;
+    readonly log: {
+        (...argv: any[]): void;
+        once(...argv: any[]): void;
+        off: boolean;
+    };
+}

types/static/node.d.ts

@@ -0,0 +1,13 @@
+import { IGunChainReference } from '../chain';
+export interface IGunStaticNode {
+    /** Returns true if data is a gun node, otherwise false. */
+    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: 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;
+}

types/static/sea.d.ts

@@ -0,0 +1,56 @@
+/** @see https://gun.eco/docs/SEA */
+export interface IGunStaticSEA {
+    /** If you want SEA to throw while in development, turn SEA.throw = true on, but please do not use this in production. */
+    throw?: boolean;
+    /** Last known error */
+    err?: Error;
+    /**
+     * This gives you a Proof of Work (POW) / Hashing of Data
+     * @param data The data to be hashed, work to be performed on.
+     * @param pair (salt) You can pass pair of keys to use as salt. Salt will prevent others to pre-compute the work,
+     *  so using your public key is not a good idea. If it is not specified, it will be random,
+     *  which ruins your chance of ever being able to re-derive the work deterministically
+     * @param callback function to executed upon execution of proof
+     * @param opt default: {name: 'PBKDF2', encode: 'base64'}
+     */
+    work(data: any, pair?: any, callback?: (data: string | undefined) => void, opt?: Partial<{
+        name: 'SHA-256' | 'PBKDF2';
+        encode: 'base64' | 'base32' | 'base16';
+        /** iterations to use on subtle.deriveBits */
+        iterations: number;
+        salt: any;
+        hash: string;
+        length: any;
+    }>): Promise<string | undefined>;
+    /**
+     * This generates a cryptographically secure public/private key pair - be careful not to leak the private keys!
+     * Note: API subject to change we may change the parameters to accept data and work, in addition to generation.
+     * You will need this for most of SEA's API, see those method's examples.
+     * The default cryptographic primitives for the asymmetric keys are ECDSA for signing and ECDH for encryption.
+     */
+    pair(cb: (data: CryptoKeyPair) => void, opt?: {}): Promise<CryptoKeyPair | undefined>;
+    /**
+     * Adds a signature to a message, for data that you want to prevent attackers tampering with.
+     * @param data is the content that you want to prove is authorized.
+     * @param pair is from .pair.
+     */
+    sign(data: any, pair: CryptoKeyPair): Promise<string | undefined>;
+    /**
+     * Gets the data if and only if the message can be verified as coming from the person you expect.
+     * @param message is what comes from .sign.
+     * @param pair from .pair or its public key text (pair.pub).
+     */
+    verify(message: any, pair: CryptoKeyPair | string): Promise<unknown>;
+    /**
+     * Takes some data that you want to keep secret and encrypts it so nobody else can read it.
+     * @param data is the content that you want to encrypt.
+     * @param pair from .pair or a passphrase you want to use as a cypher to encrypt with.
+     */
+    encrypt(data: any, pair: CryptoKeyPair | string): Promise<string>;
+    /**
+     * Read the secret data, if and only if you are allowed to.
+     * @param message is what comes from .encrypt.
+     * @param pair from .pair or the passphrase to decypher the message.
+     */
+    decrypt(message: any, pair: CryptoKeyPair | string): Promise<unknown>;
+}

types/types.d.ts

@@ -0,0 +1,37 @@
+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>;
+export declare type DisallowArray<T> = ArrayOf<T> extends never ? T : never;
+/** These types cannot be stored on Gun */
+export declare type AlwaysDisallowedType<T> = T extends (...args: any[]) => void ? never : T extends {
+    new (...args: any[]): any;
+} ? never : AccessObject<T>;
+export declare type AccessObject<T> = T extends object ? {
+    [key in keyof T]: (AlwaysDisallowedType<T[key]> extends never ? never : AccessObject<T[key]>);
+} : T;
+/** 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 | IGunChainReference<DataType>;
+export declare type AckCallback = (ack: {
+    err: Error;
+    ok: any;
+} | {
+    err: undefined;
+    ok: string;
+}) => void;
+export declare type IGunCryptoKeyPair = Record<'pub' | 'priv' | 'epub' | 'epriv', string>;
+export interface IGunRecordNodeRawBase {
+    '#': string;
+}
+export interface IGunRecordNodeRawExtra<DataType> extends IGunRecordNodeRawBase {
+    '>': Record<keyof DataType, number>;
+}
+export interface IGunRecordNodeRaw<DataType> {
+    '_': IGunRecordNodeRawExtra<DataType>;
+}
+export declare type IGunRecordNode<DataType> = {
+    [K in keyof DataType]: IGunRecordNodeRawBase;
+} & IGunRecordNodeRaw<DataType>;
+export declare type IGunRecordData<DataType> = DataType & IGunRecordNodeRaw<DataType>;