pwix:options

What is it ?

A class to manage configuration options.

Rationale

Most of the usual configuration options are either boolean or strings, or a derivative of these as array of booleans or array of strings.

We want that our configuration options also accept functions which returns expected result.

More we want these configuration options be reactive.

The exported Base class provides the methods required to:

check the provided option
check the result of a provided function
associates each configuration option with a reactive var
making sure the returned value is compatible with the desired type and is reactive.

Installation

This Meteor package is installable with the usual command:

    meteor add pwix:options
    meteor npm install lodash --save

Usage

After having installed the package, then derive the provided Options.Base class once per configuration set, and provide a getter/setter method for each configuration option you want to manage.

Example

Say you have a package or an application which accepts a configuration object as:

1    conf = {
2        level: {
3            key1: value1,
4            key2: value2
5        }
6        key3: value3
7    }

So you have to write a class which extends Options.Base with one method for each configuration parameter:

1    export class myOptions extends Options.Base {
2
3        static Constants = [
4            KEY_CONSTANT_A,
5            KEY_CONSTANT_A
6        ];
7
8        /**
9        * Constructor
10        * @param {Object} options the options to be managed
11        *
12        * The Base base class takes care of managing the known options, either as a value, or as a function which return a value.
13        * In some case where the expected value is a string, the base class also can accept an object with 'namespace' and 'i18n' keys.
14        * All options are accepted as long as the corresponding getter/setter method exists in this derived class.
15        *
16        * @returns {myOptions}
17        */
18        constructor( options ){
19            super( options );
20            return this;
21        }
22
23        /**
24        * Getter/Setter
25        * @param {String|Function} value the prefix of the collection's name
26        * @returns {String}
27        */
28        'level.key1'( value ){
29            return this.base_gsStringArrayFn( 'level.key1', value, { default: defaults.level.key1 });
30        }
31
32        /**
33        * Getter/Setter
34        * @param {String|Function} value the default access mode of a new forum
35        * @returns {String}
36        */
37        'level.key2'( value ){
38            return this.base_gsStringFn( 'level.key2', value, { default: defaults.level.key1, ref: myOptions.Constants });
39        }
40
41        /**
42        * Getter/Setter
43        * @param {String|Function} value the default access mode of a new forum
44        * @returns {String}
45        */
46        key3( value ){
47            return this.base_gsIntegerFn( 'key3', value, { default: defaults.common.key3 });
48        }
49    }

What does it provide ?

`Options`

The globally exported object.

Classes

Options.Base

The class to be derived by the consumer.
- Base( [options<Object>] )
  
  The constructor.
  
  It accepts an optional list of options as an argument.
  
  If the caller expects the option values to change over the time, then it should also call the corresponding getters from inside an autorun() section.
- base_get_set_options()
  
  Returns the list of set options.
  
  This may not be the full list of known options. We only return here the options which have been explicitely set. So calling base_get_set_options() let you know which options have been really set.
- base_gsBoolFn( name, value [, opts ] )
  
  Manage a boolean argument.
  
  Accepts also as a value a function which returns a boolean argument.
  
  opts is an optional option object with keys:
  - check
    
    An optional check function, called with the provided value, must return true or false
  - default
    
    An optional default value, or a function which returns the default value
  Note that if the returned/computed value is not valid according to the check() function, then we return the default value, which may itself be undefined. If the caller has not provided any valid default value, he must so prepare to handle that.
- base_gsFn( name, value [, opts ] )
  
  Manage a function argument.
- base_gsIntegerFn( name, value [, opts ] )
  
  Manage an integer argument.
  
  Accepts also as a value a function which returns an integer argument.
- base_gsIntegerStringFn( name, value [, opts ] )
  
  Manage an argument as integer or a string.
  
  Accepts also as a value a function which returns an integer or a string argument.
- base_gsObjectFn( name, value [, opts ] )
  
  Manage an opaque object.
  
  Accepts also as a value a function which returns an object.
- base_gsRegexArrayFn( name, value [, opts ] )
  
  Manage a regular expression or an array of regular expressions.
  
  Accepts also as a value a function which returns a regular expression or an array of regular expressions.
  
  Returns an array of regular expressions, which may be empty.
- base_gsStringArrayFn( name, value [, opts ] )
  
  Manage a string or an array of strings.
  
  Accepts also as a value a function which returns a string or an array of strings.
- base_gsStringFn( name, value [, opts ] )
  
  Manage a string argument.
  
  Accepts also as a value a function which returns a string argument.
  
  Besides check and default keys, opts also accepts a ref argument which is expected to address an array of accepted values.
- base_gsStringObjectFn( name, value [, opts ] )
  
  Manage a string or an object.
  
  Accepts also as a value a function which returns a string or an object.
  
  This is actually a method to handle internationalization where strings are provided not by their localized text value, but by an object { namespace, i18n }.
- base_options()
  
  Returns the list of used options.
  
  This may not be the full list of known options. We only return here the options which have been either got or set.
- base_set( options<Object> )
  
  Set the new option values.

Functions

Options.configure()

The configuration function (see below)[#configuration].

Configuration

The package's behavior can be configured through a call to the Options.configure() function, with just a single javascript object argument, which itself should only contains the options you want override.

Known configuration options are:

errOnUnmanaged

Whether an unmanaged option, which do not have any implementation method, should trigger an error.

Defaults to false.
verbosity

Define the expected verbosity level.

The accepted value can be:
- Options.C.Verbose.NONE
  
  Do not display any trace log to the console
or any or-ed combination of following:
- Options.C.Verbose.CONFIGURE
  
  Trace Options.configure() calls and their result

Please note that Options.configure() method should be called in the same terms both in client and server sides.

Remind too that Meteor packages are instanciated at application level. They are so only configurable once, or, in other words, only one instance has to be or can be configured. Addtionnal calls to Options.configure() will just override the previous one. You have been warned: only the application should configure a package.

NPM peer dependencies

In accordance with advices from the Meteor Guide, we do not hardcode NPM dependencies in package.js. Instead we check npm versions of installed packages at runtime, on server startup, in development environment.

Dependencies as of v 2.2.0:

1    'lodash': '^4.17.0'

Each of these dependencies should be installed at application level:

    meteor npm install <package> --save

Translations

New and updated translations are willingly accepted, and more than welcome. Just be kind enough to submit a PR on the Github repository.

Cookies and comparable technologies

None at the moment.

Issues & help

In case of support or error, please report your issue request to our Issues tracker.

P. Wieser <<<<<<< HEAD

Last updated on 2026, Apr. 1st

=======

Last updated on 2026, Apr. 13rd

vnext