[FABN-891] Make documentation and types consistent

This CR fixes inconsistency between documentation and type definitions.

This includes:
  - Fix for the name of some objects (e.g. "Options" -> "Opts")
  - Add some missing fields in the objects in doc or type
  - Fix types of some fields in the documentation
    (e.g. "Peer[]" -> "Peer[] | string[]")
  - Remove duplicated documentation (ChaincodeInfo)
  - Remove excess fields from type (and test)

FABN-891 #done

Change-Id: Id73ee7e5507da5a4c2411445490152cfbe1ed86e
Signed-off-by: Taku Shimosawa <[email protected]>

fabric-client/lib/Channel.js

@@ -358,13 +358,6 @@ const Channel = class {
 		return this._name;
 	}
 
-	/**
-	 * @typedef {Object} ChaincodeInfo Object used internally to store chaincodes
-	 *          names and versions found on this channel.
-	 * @property {string} name - The name of the chaincode
-	 * @property {string} version - The version of the chaincode
-	 */
-
 	/**
 	 * @typedef {Object} DiscoveryResultMSPConfig
 	 * @property {string} rootCerts List of root certificates trusted by this MSP.
@@ -1304,7 +1297,7 @@ const Channel = class {
 
 	/**
 	 * @typedef {Object} JoinChannelRequest
-	 * @property {Peer[]} targets - Optional. An array of Peer objects or Peer names that will
+	 * @property {Peer[] | string[]} targets - Optional. An array of Peer objects or Peer names that will
 	 *                              be asked to join this channel. When using Peer names or left
 	 *                              empty (use default targets) there must be a loaded network
 	 *                              configuration.
@@ -2046,9 +2039,9 @@ const Channel = class {
 
 	/**
 	 * @typedef {Object} ChaincodeInstantiateUpgradeRequest
-	 * @property {Peer[]} targets - Optional. An array of endorsing
-	 *           {@link Peer} objects as the targets of the request. When this
-	 *           parameter is omitted the target list will include peers assigned
+	 * @property {Peer[] | string[]} targets - Optional. An array of endorsing
+	 *           {@link Peer} objects or peer names as the targets of the request.
+	 *           When this parameter is omitted the target list will include peers assigned
 	 *           to this channel instance that are in the endorsing role.
 	 * @property {string} chaincodeType - Optional. Type of chaincode. One of
 	 *           'golang', 'car', 'java' or 'node'. Default is 'golang'. Note that 'java'
@@ -2247,7 +2240,7 @@ const Channel = class {
 
 	/**
 	 * @typedef {Object} ChaincodeInvokeRequest
-	 * @property {Peer[]} targets - Optional. The peers that will receive this request,
+	 * @property {Peer[] | string[]} targets - Optional. The peers that will receive this request,
 	 *           when not provided the list of peers added to this channel object will
 	 *           be used. When this channel has been initialized using the discovery
 	 *           service the proposal will be sent to the peers on the list provided
@@ -2412,12 +2405,12 @@ const Channel = class {
 
 	/**
 	 * @typedef {Object} TransactionRequest
-	 * @property {array} proposalResponses - An array of or a single
+	 * @property {ProposalResponse[]} proposalResponses - An array of or a single
 	 *           {@link ProposalResponse} object containing the response from the
 	 *           [endorsement]{@link Channel#sendTransactionProposal} call
-	 * @property {Object} proposal - A Proposal object containing the original
+	 * @property {Proposal} proposal - A Proposal object containing the original
 	 *           request for endorsement(s)
-	 * @property {Object} txID - Optional. - Must be the transaction ID object
+	 * @property {TransactionId} txID - Optional. - Must be the transaction ID object
 	 *           used in the proposal endorsement. The transactionID will
 	 *           only be used to determine if the signing of the request
 	 *           should be done by the admin identity or the user assigned
@@ -3147,6 +3140,10 @@ function loadConfigValue(config_items, versions, config_value, group_name, org,
  *           event listener registration? All peers can produce events, but the
  *           appliatiion typically only needs to connect to one.
  *           Default: true
+ *
+ * @property {boolean} discover - Optional. This peer may be the target of service
+ *           discovery.
+ *           Default: true
  */
 
 /**

fabric-client/lib/Client.js

@@ -624,7 +624,7 @@ const Client = class extends BaseClient {
 	/**
 	 * @typedef {Object} ChannelRequest
 	 * @property {string} name - Required. The name of the new channel
-	 * @property {Orderer} orderer - Required. An Orderer object representing the
+	 * @property {Orderer | string} orderer - Required. An Orderer object or an orderer name representing the
 	 *                               orderer node to send the channel create request
 	 * @property {byte[]} envelope - Optional. Bytes of the envelope object containing all
 	 *                               required settings and signatures to initialize this channel. This envelope
@@ -634,8 +634,8 @@ const Client = class extends BaseClient {
 	 * @property {byte[]} config - Optional. Protobuf ConfigUpdate object extracted from a ConfigEnvelope
 	 *                             created by the configtxgen tool. See [extractChannelConfig()]{@link Client#extractChannelConfig}.
 	 *                             The ConfigUpdate object may also be created by the configtxlator tool.
-	 * @property {ConfigSignature[]} signatures - Required. The list of signatures required by the
-	 *                               channel creation or update policy when using the `config` parameter.
+	 * @property {ConfigSignature[] | string[]} signatures - Required. The list of signatures required by the
+	 *                                                       channel creation or update policy when using the `config` parameter.
 	 * @property {TransactionID} txId - Required. TransactionID object with the transaction id and nonce
 	 */
 
@@ -895,8 +895,8 @@ const Client = class extends BaseClient {
 
 	/**
 	 * @typedef {Object} ChaincodeInstallRequest
-	 * @property {Peer[]} targets - Optional. An array of Peer objects where the
-	 *           chaincode will be installed. When excluded, the peers assigned
+	 * @property {Peer[] | string[]} targets - Optional. An array of Peer objects or peer names
+	 *           where the chaincode will be installed. When excluded, the peers assigned
 	 *           to this client's organization will be used as defined in the
 	 *           network configuration. If the 'channelNames' property is included,
 	 *           the target peers will be based the peers defined in the channels.
@@ -926,14 +926,15 @@ const Client = class extends BaseClient {
 	 *           by this property and in this client's organization and that are
 	 *           in the endorsing or chain code query role on the named channel
 	 *           will be selected.
+	 * @property {TransactionID} txId - Optional. TransactionID object for this request.
 	 */
 
 	/**
 	 * All calls to the endorsing peers for proposal endorsement return this
 	 * standard array of objects.
 	 *
 	 * @typedef {array} ProposalResponseObject
-	 * @property {array} index:0 - Array of ProposalResponse objects from the
+	 * @property {ProposalResponse[]} index:0 - Array of ProposalResponse objects from the
 	 *           endorsing peers
 	 * @property {Object} index:1 - The original Proposal object needed when
 	 *           sending the transaction request to the orderer
@@ -1450,8 +1451,8 @@ const Client = class extends BaseClient {
 
 	/**
 	 * @typedef {Object} UserOpts
-	 * @property {string} username {string} - the user name used for enrollment
-	 * @property {string} mspid {string} - the MSP id
+	 * @property {string} username - the user name used for enrollment
+	 * @property {string} mspid - the MSP id
 	 * @property {CryptoContent} cryptoContent - the private key and certificate
 	 * @property {boolean} skipPersistence - whether to save this new user object into persistence.
 	 */

fabric-client/lib/Orderer.js

@@ -97,6 +97,7 @@ class Orderer extends Remote {
 	/**
 	 * @typedef {Object} BroadcastResponse
 	 * @property {string} status - Value is 'SUCCESS' or a descriptive error string
+	 * @property {string} info - Optional. Additional information about the status
 	 */
 
 	/**

fabric-client/types/base.d.ts

@@ -1,12 +1,18 @@
-import { ICryptoSuite, ICryptoKeyStore, IKeyValueStore } from 'fabric-client';
+/**
+ * Copyright 2018 Zhao Chaoyi, All Rights Reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { CryptoSetting, ICryptoSuite, ICryptoKeyStore, IKeyValueStore } from 'fabric-client';
 
 export abstract class BaseClient {
     constructor();
     static setLogger(logger: any): void;
     static addConfigFile(path: string): void;
     static getConfigSetting(name: string, default_value?: any): any;
     static setConfigSetting(name: string, value: any): void;
-    static newCryptoSuite(): ICryptoSuite;
+    static newCryptoSuite(setting?: CryptoSetting): ICryptoSuite;
     static newCryptoKeyStore(obj?: { path: string }): ICryptoKeyStore;
     static newDefaultKeyValueStore(obj?: { path: string }): Promise<IKeyValueStore>;
     static normalizeX509(raw: string): string;

fabric-client/types/index.d.ts

@@ -1,17 +1,7 @@
 /**
  * Copyright 2017 Kapil Sachdeva All Rights Reserved.
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing, software
- *  distributed under the License is distributed on an "AS IS" BASIS,
- *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *  See the License for the specific language governing permissions and
- *  limitations under the License.
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 import FabricCAServices = require('fabric-ca-client');
@@ -26,7 +16,7 @@ declare class ChaincodeChannelEventHandle {
 }
 
 declare class Remote {
-  constructor(url: string, opts?: Client.ConnectionOptions);
+  constructor(url: string, opts?: Client.ConnectionOpts);
   getName(): string;
   setName(name: string): void;
   getUrl(): string;
@@ -42,10 +32,10 @@ declare class Client extends BaseClient {
   setDevMode(mode: boolean): void;
   newChannel(name: string): Client.Channel;
   getChannel(name?: string, throwError?: boolean): Client.Channel;
-  newPeer(url: string, opts?: Client.ConnectionOptions): Client.Peer;
+  newPeer(url: string, opts?: Client.ConnectionOpts): Client.Peer;
   getPeer(name: string): Client.Peer;
   getPeersForOrg(mspid?: string): Client.Peer[];
-  newOrderer(url: string, opts?: Client.ConnectionOptions): Client.Orderer;
+  newOrderer(url: string, opts?: Client.ConnectionOpts): Client.Orderer;
   getOrderer(name: string): Client.Orderer;
   getPeersForOrgOnChannel(channel_names: string | string[]): Client.ChannelPeer[];
   getCertificateAuthority(): FabricCAServices;
@@ -67,7 +57,7 @@ declare class Client extends BaseClient {
   getUserContext(name: string, checkPersistence?: boolean): Promise<Client.User> | Client.User;
   loadUserFromStateStore(name: string): Promise<Client.User>;
   getStateStore(): Client.IKeyValueStore;
-  createUser(opts: Client.UserOptions): Promise<Client.User>;
+  createUser(opts: Client.UserOpts): Promise<Client.User>;
 
   getTargetPeers(request_targets: string | string[] | Client.Peer | Client.Peer[]): Client.Peer[];
   getTargetOrderers(request_orderer: string | Client.Orderer): Client.Orderer;
@@ -116,14 +106,21 @@ declare namespace Client {
     setCryptoKeyStore(cryptoKeyStore: ICryptoKeyStore): void;
   }
 
+  export interface CryptoSetting {
+    software: boolean;
+    keysize: number;
+    algorithm: string;
+    hash: string;
+  }
+
   export interface UserConfig {
     enrollmentID: string;
     name: string
     roles?: string[];
     affiliation?: string;
   }
 
-  export interface ConnectionOptions {
+  export interface ConnectionOpts {
     pem?: string;
     clientKey?: string;
     clientCert?: string;
@@ -221,6 +218,7 @@ declare namespace Client {
     chaincodeQuery?: boolean;
     ledgerQuery?: boolean;
     eventSource?: boolean;
+    discover?: boolean;
   }
 
   export class ChannelPeer {
@@ -269,20 +267,19 @@ declare namespace Client {
   export interface TransactionRequest {
     proposalResponses: ProposalResponse[];
     proposal: Proposal;
-    admin?: boolean;
     txId?: TransactionId;
     orderer?: string | Orderer;
   }
 
   export interface BroadcastResponse {
     status: string;
-    info: string;
+    info?: string;
   }
 
   export type ProposalResponseObject = [Array<Client.ProposalResponse>, Client.Proposal];
 
   export interface OrdererRequest {
-    txId: TransactionId;
+    txId?: TransactionId;
     orderer?: string | Orderer;
   }
 
@@ -316,7 +313,7 @@ declare namespace Client {
   export interface ProposalResponse {
     version: number;
     timestamp: Date;
-    response: ResponseObject;
+    response: Response;
     payload: Buffer;
     endorsement: any;
   }
@@ -332,11 +329,11 @@ declare namespace Client {
     close(): void;
     checkConnection(force_reconnect: boolean): string;
     registerChaincodeEvent(ccid: string, eventname: string, onEvent: (event: ChaincodeEvent, block_number?: number, tx_id?: string, tx_status?: string) => void,
-      onError?: (err: Error) => void, options?: RegistrationOptions): ChaincodeChannelEventHandle;
+      onError?: (err: Error) => void, options?: RegistrationOpts): ChaincodeChannelEventHandle;
     unregisterChaincodeEvent(handle: ChaincodeChannelEventHandle, throwError?: boolean): void;
-    registerBlockEvent(onEvent: (block: Block) => void, onError?: (err: Error) => void, options?: RegistrationOptions): number;
+    registerBlockEvent(onEvent: (block: Block) => void, onError?: (err: Error) => void, options?: RegistrationOpts): number;
     unregisterBlockEvent(block_registration_number: number, throwError: boolean): void;
-    registerTxEvent(txId: string, onEvent: (txId: string, code: string, block_number: number) => void, onError?: (err: Error) => void, options?: RegistrationOptions): string;
+    registerTxEvent(txId: string, onEvent: (txId: string, code: string, block_number: number) => void, onError?: (err: Error) => void, options?: RegistrationOpts): string;
     unregisterTxEvent(txId: string, throwError?: boolean): void;
   }
 
@@ -346,7 +343,7 @@ declare namespace Client {
   }
 
   export class Peer extends Remote {
-    constructor(url: string, opts?: ConnectionOptions);
+    constructor(url: string, opts?: ConnectionOpts);
     close(): void;
     setRole(role: string, isIn: boolean): void;
     isInRole(role: string): boolean;
@@ -355,7 +352,7 @@ declare namespace Client {
   }
 
   export class Orderer extends Remote {
-    constructor(url: string, opts?: ConnectionOptions);
+    constructor(url: string, opts?: ConnectionOpts);
     close(): void;
     sendBroadcast(envelope: Buffer): Promise<BroadcastResponse>;
     sendDeliver(envelope: Buffer): Promise<any>;
@@ -394,6 +391,7 @@ declare namespace Client {
   export interface ChaincodeInstallRequest {
     targets?: Peer[] | string[];
     chaincodePath: string;
+    metadataPath?: string;
     chaincodeId: string;
     chaincodeVersion: string;
     chaincodePackage?: Buffer;
@@ -408,6 +406,7 @@ declare namespace Client {
     chaincodeId: string;
     chaincodeVersion: string;
     txId: TransactionId;
+    'collections-config'?: string;
     transientMap?: any;
     fcn?: string;
     args?: string[];
@@ -421,6 +420,8 @@ declare namespace Client {
     transientMap?: any;
     fcn?: string;
     args: string[];
+    ignore?: string[];
+    preferred?: string[];
   }
 
   export interface ChaincodeQueryRequest {
@@ -448,7 +449,7 @@ declare namespace Client {
     password?: string;
   }
 
-  export interface UserOptions {
+  export interface UserOpts {
     username: string;
     mspid: string;
     cryptoContent: CryptoContent;
@@ -488,7 +489,7 @@ declare namespace Client {
     channels: ChannelInfo[];
   }
 
-  export interface ResponseObject {
+  export interface Response {
     status: Client.Status;
     message: string;
     payload: Buffer;
@@ -505,9 +506,9 @@ declare namespace Client {
     signature_header: ByteBuffer;
   }
 
-  export interface RegistrationOptions {
+  export interface RegistrationOpts {
     startBlock?: number;
-    endBlock?: number;
+    endBlock?: number | "newest";
     unregister?: boolean;
     disconnect?: boolean;
   }

test/typescript/test.ts

@@ -433,8 +433,7 @@ test('use the connection profile file', (t) => {
 			}
 			let request: TransactionRequest = {
 				proposalResponses: proposalResponses,
-				proposal: proposal,
-				admin: true
+				proposal: proposal
 			};
 
 			let promises = [];