Improved fn comments and definitions

src/PKPass.ts

@@ -220,9 +220,7 @@ export default class PKPass extends Bundle {
 	 * Allows setting a transitType property
 	 * for a boardingPass.
 	 *
-	 * It will (automatically) throw an exception
+	 * @throws if current type is not "boardingPass".
-	 * if current type is not "boardingPass".
-	 *
 	 * @param value
 	 */
 
@@ -246,8 +244,7 @@ export default class PKPass extends Bundle {
 	 * Allows getting the current transitType
 	 * from pass props.
 	 *
-	 * It will (automatically) throw an exception
+	 * @throws (automatically) if current type is not "boardingPass".
-	 * if current type is not "boardingPass".
 	 */
 
 	public get transitType() {
@@ -257,9 +254,9 @@ export default class PKPass extends Bundle {
 	/**
 	 * Allows accessing to primaryFields object.
 	 *
-	 * It will (automatically) throw an exception
+	 * @throws (automatically) if no valid pass.json
-	 * if no valid pass.json has been parsed yet
+	 * 		has been parsed yet or, anyway, if current
-	 * or, anyway, if it has not a valid type.
+	 * 		instance has not a valid type set yet.
 	 */
 
 	public get primaryFields(): Schemas.Field[] {
@@ -269,10 +266,9 @@ export default class PKPass extends Bundle {
 	/**
 	 * Allows accessing to secondaryFields object
 	 *
-	 * It will (automatically) throw an exception
+	 * @throws (automatically) if no valid pass.json
-	 * if no valid pass.json has been parsed yet
+	 * 		has been parsed yet or, anyway, if current
-	 * or, anyway, if a valid type has not been
+	 * 		instance has not a valid type set yet.
-	 * set yet.
 	 */
 
 	public get secondaryFields(): Schemas.Field[] {
@@ -282,15 +278,14 @@ export default class PKPass extends Bundle {
 	/**
 	 * Allows accessing to auxiliaryFields object
 	 *
-	 * It will (automatically) throw an exception
-	 * if no valid pass.json has been parsed yet
-	 * or, anyway, if a valid type has not been
-	 * set yet.
-	 *
 	 * For Typescript users: this signature allows
 	 * in any case to add the 'row' field, but on
 	 * runtime they are only allowed on "eventTicket"
 	 * passes.
+	 *
+	 * @throws (automatically) if no valid pass.json
+	 * 		has been parsed yet or, anyway, if current
+	 * 		instance has not a valid type set yet.
 	 */
 
 	public get auxiliaryFields(): Schemas.FieldWithRow[] {
@@ -300,10 +295,9 @@ export default class PKPass extends Bundle {
 	/**
 	 * Allows accessing to headerFields object
 	 *
-	 * It will (automatically) throw an exception
+	 * @throws (automatically) if no valid pass.json
-	 * if no valid pass.json has been parsed yet
+	 * 		has been parsed yet or, anyway, if current
-	 * or, anyway, if a valid type has not been
+	 * 		instance has not a valid type set yet.
-	 * set yet.
 	 */
 
 	public get headerFields(): Schemas.Field[] {
@@ -313,10 +307,9 @@ export default class PKPass extends Bundle {
 	/**
 	 * Allows accessing to backFields object
 	 *
-	 * It will (automatically) throw an exception
+	 * @throws (automatically) if no valid pass.json
-	 * if no valid pass.json has been parsed yet
+	 * 		has been parsed yet or, anyway, if current
-	 * or, anyway, if a valid type has not been
+	 * 		instance has not a valid type set yet.
-	 * set yet.
 	 */
 
 	public get backFields(): Schemas.Field[] {
@@ -327,9 +320,9 @@ export default class PKPass extends Bundle {
 	 * Allows setting a pass type.
 	 *
 	 * **Warning**: setting a type with this setter,
-	 * will reset all the imported or manually
+	 * will reset all the fields (primaryFields,
-	 * setted fields (primaryFields, secondaryFields,
+	 * secondaryFields, headerFields, auxiliaryFields, backFields),
-	 * headerFields, auxiliaryFields, backFields)
+	 * both imported or manually set.
 	 */
 
 	public set type(nextType: Schemas.PassTypesProps | undefined) {
@@ -396,27 +389,28 @@ export default class PKPass extends Bundle {
 	// **************************** //
 
 	/**
-	 * Allows adding a new asset inside the pass / bundle;
+	 * Allows adding a new asset inside the pass / bundle with
-	 * If an empty buffer is passed, it won't be added to
+	 * the following exceptions:
-	 * the bundle.
 	 *
-	 * `manifest.json` and `signature` files will be ignored.
+	 * - Empty buffers are ignored;
-	 *
+	 * - `manifest.json` and `signature` files will be ignored;
-	 * If a `pass.json` is passed to this method (and it has
+	 * - `pass.json` will be read validated and merged in the
-	 * not been added previously), it will be read, validated
+	 * 	current instance, if it wasn't added previously.
-	 * and merged in the current instance. Its properties
+	 * 	It's properties will overwrite the instance ones.
-	 * will overwrite the ones setted through methods.
+	 * 	You might loose data;
-	 *
+	 * - `pass.strings` files will be read, parsed and merged
-	 * If a `pass.strings` file is passed, it will be read, parsed
+	 * 	with the current translations. Comments will be ignored;
-	 * and merged with the translations added previously.
+	 * - `personalization.json` will be read, validated and added.
-	 * Comments will be ignored.
+	 * 	They will be stripped out when exporting the pass if
+	 * 	it won't have NFC details or if any of the personalization
+	 * 	files is missing;
 	 *
 	 * @param pathName
 	 * @param buffer
 	 */
 
 	public addBuffer(pathName: string, buffer: Buffer): void {
-		if (!buffer) {
+		if (!buffer?.length) {
 			return;
 		}
 
@@ -508,11 +502,6 @@ export default class PKPass extends Bundle {
 	 * Given data from a pass.json, reads them to bring them
 	 * into the current pass instance.
 	 *
-	 * **Warning**: if this file contains a type (boardingPass,
-	 * coupon, and so on), it will replace the current one,
-	 * causing, therefore, the destroy of the fields added
-	 * previously.
-	 *
 	 * @param data
 	 */
 
@@ -749,7 +738,7 @@ export default class PKPass extends Bundle {
 	 * If the language already exists, translations will be
 	 * merged with the existing ones.
 	 *
-	 * Setting `translations` to `null`, fully deletes a language,
+	 * Setting `translations` to `null` fully deletes a language,
 	 * its translations and its files.
 	 *
 	 * @see https://developer.apple.com/documentation/walletpasses/creating_the_source_for_a_pass#3736718
@@ -803,7 +792,10 @@ export default class PKPass extends Bundle {
 	/**
 	 * Allows to specify an expiration date for the pass.
 	 *
+	 * Pass `null` to remove the expiration date.
+	 *
 	 * @param date
+	 * @throws if pass is frozen due to previous export
 	 * @returns
 	 */
 
@@ -840,6 +832,7 @@ export default class PKPass extends Bundle {
 	 *
 	 * @see https://developer.apple.com/documentation/walletpasses/pass/beacons
 	 * @param beacons
+	 * @throws if pass is frozen due to previous export
 	 * @returns
 	 */
 
@@ -876,6 +869,7 @@ export default class PKPass extends Bundle {
 	 *
 	 * @see https://developer.apple.com/documentation/walletpasses/pass/locations
 	 * @param locations
+	 * @throws if pass is frozen due to previous export
 	 * @returns
 	 */
 
@@ -899,7 +893,10 @@ export default class PKPass extends Bundle {
 	 * Allows setting a relevant date in which the OS
 	 * should show this pass.
 	 *
+	 * Pass `null` to remove relevant date from this pass.
+	 *
 	 * @param {Date | null} date
+	 * @throws if pass is frozen due to previous export
 	 */
 
 	public setRelevantDate(date: Date | null): void {
@@ -925,8 +922,15 @@ export default class PKPass extends Bundle {
 	 * will be shown to the user, without any possibility
 	 * to change it.
 	 *
+	 * It accepts either a string from which all formats will
+	 * be generated or a specific set of barcodes objects
+	 * to be validated and used.
+	 *
+	 * Pass `null` to remove all the barcodes.
+	 *
 	 * @see https://developer.apple.com/documentation/walletpasses/pass/barcodes
 	 * @param barcodes
+	 * @throws if pass is frozen due to previous export
 	 * @returns
 	 */
 
@@ -984,6 +988,7 @@ export default class PKPass extends Bundle {
 	 *
 	 * @see https://developer.apple.com/documentation/walletpasses/pass/nfc
 	 * @param data
+	 * @throws if pass is frozen due to previous export
 	 * @returns
 	 */
 

src/utils.ts

@@ -109,7 +109,9 @@ export function cloneRecursive<T extends Object>(object: T) {
 	return objectCopy;
 }
 
-export function assertUnfrozen(instance: InstanceType<typeof Bundle>) {
+export function assertUnfrozen(
+	instance: InstanceType<typeof Bundle>,
+): asserts instance is Bundle & { isFrozen: false } {
 	if (instance.isFrozen) {
 		throw new Error(Messages.BUNDLE.CLOSED);
 	}