Nth Permutation Mathematics

# npm

Miss any of our Open RFC calls?Watch the recordings here! »

## yes-sir

1.0.1 • Public • Published

## JavaScript Assertion Library

Have you ever wanted a nice and simple assertion library?
Yes, sir!
Do you want it to be easy to understand and use?
Yes, sir!
Do you want it to be multi-lingual?
Um, I guess, sir!
Well, that's good enough for me. Let's get into the intro.

## Yes-Sir is an assertion library.

But, not your usual assertion library. Unless you want it to be.
It's also got an simple and intuitive "is" system to make all the inevitable `if` statements in your code easier to read and write.
Using its assertion system, you can check that an argument exists (or not) or if it is a `String`, for example. And, if it isn't, Yes-Sir will automatically throw an error. "No, sir"

All functions in Yes-Sir return true if they completed successfully and false if not.

### Lets check out that "is" system:

It uses an English-like structure, mixed with a JavaScript-y style. To start a "sentence", just type `Is([value])`. You can then do your checks, and see if they are correct:

``````// is xx a
Is(10).a(Object) // returns false
Is({}).a(Object) // returns true
Is("").a("string") // returns true
Is("").a(Array) // returns false

// is xx true
Is("10").true() // returns false
Is(true).true() // returns true

// is xx not xx
Is(10).not.a(Object) // returns true
Is("").not.a("string") // returns false
``````

However, this will not do anything except for return `true` or `false`. If you want the function to automatically log any errors to the console, you can use `Log(message).if(value).xxx`:

``````// log "oh no" if xx is a
Log("oh no").if(10).is.a(Object) // returns false
Log("oh no").if({}).is.a(Object) // returns true; logs "oh no"
Log("oh no").if("").is.a("string") // returns true; logs "oh no"
Log("oh no").if("").is.a(Array) // returns false

// log "its true" if xx is true
Log("its true").if("10").is.true() // returns false
Log("its true").if(true).is.true() // returns true; logs "its true

// log "it isnt" if xx is not xx
Log("it isnt").if(10).is.not.a(Object) // returns true; logs "it isnt"
Log("it isnt").if("").is.not.a("string") // returns false
``````

This system (and its "parser") I have named "English". (Yes. Very original.)

### And also the assertion system

There are two ways that the assertion system can be used. Like above, and like normal.

To use it like above, use `Force`:

``````Force(10).as.true() // AssertError: 10 must be true
// [with EN-gb set as the current language]

Force(true).as.true() // nothing

Force(true).as.false() // AssertError: 10 must be false
// [with EN-gb set as the current language]

Force(true).as.not.false() // nothing

Force(true).as.a("string"); // AssertError: true must be a(n) string
// [with EN-gb set as the current language]
``````

or `Throw` (like `Log`) if you want to throw an error with a custom message

``````Throw("oh no").if(true).is.true() // AssertError: oh no: true must not be true
// [with EN-gb set as the current language]
``````

Or you can just warn to the console (not throw an error)

``````Hopefully(true).is.false() // [warn] AssertWarn: true should be false
// [with EN-gb set as the current language]

Warn("just a warning").if(true).is.true() // [warn] AssertWarn: just a warning: true should not be true
``````

You can also use it like a normal assertion library:

``````Assert.true(10, "oh no"); // AssertError: oh no: 10 must be true
// [with EN-gb set as the current language]
// Much shorter than English, but harder to understand

Assert.true(10); // AssertError: 10 must be true
// [with EN-gb set as the current language]
// Removing the second argument just removes the message
``````

`Hopefully` cannot be used in this form, however.

## But how do I get it?

It's simple. Just:

2. Include it: `<script src="/path/to/yes-sir.js"></script>`
3. Include a language: `<script src="/path/to/yes-sir.lang.js"></script>`
4. Set the current language: `yessir.setLanguage(language:ISOLanguage)` (e.g. language could be `EN-gb`)
5. You're ready to rock and roll!

## Everything included

• `Is(value:*)`:

• `true()`: checks if the value is exactly equal to true

• `false()`: checks if the value is exactly equal to false

• `trueCoerced()`: checks if the value is "like" true (so 10 == true, 0 doesn't)

• `falseCoerced()`: checks if the value is "like" false (so "" == false, "foo" doesn't)

• `null()`: checks if the value is null

• `undefined()`: checks if the value is undefined (using `typeof`, not `===`)

• `a(type:String)`: checks if the `typeof [value]` is `type`

• `a(type:Constructor)`: checks if the `value` is an `instanceof [type]`

• `equalTo(value2:*)`: checks if the `value` is exactly equal to `value2`

• `like(value2:*)`: checks if the `value` is like (`==`) `value2` (`10 == true`, `"" == false`). May cause unexpected type coercion.

• `lengthEqualTo(length:Number)`: checks if `value`'s length is equal to `length`

• `lengthOver(length:Number)`: checks if `value`'s length is over `length`

• `lengthOverOrEqualTo(length:Number)`: checks if `value`'s length is over or equal to `length`

• `lengthUnder(length:Number)`: checks if `value`'s length is under `length`

• `lengthUnderOrEqualTo(length:Number)`: checks if `value`'s length is under or equal to `length`

• `over(value2:Number)`: checks if `value` is over `value2`

• `overOrEqualTo(value2:Number)`: checks if `value` is over or equal to `value2`

• `under(value2:Number)`: checks if `value` is under `value2`

• `underOrEqualTo(value2:Number)`: checks if `value` is under or equal to `value2`

• `including(includes:*)`: checks if `value` includes `includes`

• `(value2:*)`: This line is confusing. It means `Is(value)(value2)`. Alias for `Is(value).equalTo(value2)`

• `not.***`: Includes all functions above, but reverses their output (so `Is(10).not.true()` returns `true`)

• `not(value2:*)`: Alias for `Is(value).not.equalTo(value2)`

• All of the above functions are also returned by `Force(value:*).as.***` and `Hopefully(value:*).is.***` (and their message counterparts), however these throw errors and warnings respectively.

• `Assert`:

• `like(value:*, expected:*, message:String)`: checks if the `value` is like (`==`) `value2` (`10 == true`, `"" == false`) and throws `message` if not. May cause unexpected type coercion.

• `equal(value:*, expected:*, message:String)`: checks if `value` is exactly equal to `value2` and throws `message` if not.

• `notEqual(value:*, notExpected:*, message:String)`: checks if `value` is not exactly equal to `value2`. Throws `message` if this condition is not met.

• `null(value:*, message:String)`: checks if `value` is `null` and throws `message` if not.

• `notNull(value:*, message:String)`: checks if `value` is not `null`. Throws `message` if this condition is not met.

• `existant(value:*, message:String)`: checks if `value` is not null and not undefined. Throws `message` if this condition is not met.

• `notExistant(value:*, message:String)`: checks if `value` is null or undefined and throws `message` if not.

• `true(value:*, message:String)`: checks if `value` is true and throws `message` if not.

• `false(value:*, message:String)`: checks if `value` is false and throws `message` if not.

• `eTrue(value:*, message:String)`: checks if `value` evaluates to true (`10 == true`, `0` doesn't) and throws `message` if not

• `eFalse(value:*, message:String)`: checks if `value` evaluates to false (`"" == false"`, `"foo"` doesn't) and throws `message` if not

• `typeOf(value:*, type:String, message:String)`: checks if `typeof [value]` is `type` and if not, throws `message`

• `typeOf(value:*, type:Constructor, message:String)`: checks if `value` is an `instanceof [type]` and if not, throws `message`

## Language Packs

Yes-Sir includes the capability for multi-linguistics! To create a language, (after loading `yes-sir.js`), set `window.yessir.lang` to an object like the following:

For example,

``````window.yessir.lang = {
"EN-gb": { // the language name, by ISO specs
// The format to use for parsing the language.
format: "%value% %comparison% %expected%",

// The value used if a comparison should NOT happen
not: "not ",

// comparisons, pointed to by `db`
comparisons: {
shouldBe: "should %not%be",
shouldEvaluateTo: "should %not%evaluate to",

shouldBeAn: "should %not%be a(n)",

shouldBeOver: "should %not%be over",
shouldBeOverOrEqualTo: "should %not%be over or equal to",

shouldBeUnder: "should %not%be under",
shouldBeUnderOrEqualTo: "should %not%be under or equal to",

shouldInclude: "should %not%include"
},

// database of comparison types (should be an object of every function used, to define how they work
db: {
true: "shouldBe",
false: "shouldBe",

trueCoerced: "shouldEvaluateTo",
falseCoerced: "shouldEvaluateTo",

null: "shouldBe",
undefined: "shouldBe",
existant: "shouldBe",

a: "shouldBeAn",

equalTo: "shouldBe",
like: "shouldEvaluateTo",

lengthEqualTo: "shouldBe",
lengthOver: "shouldBeOver",
lengthOverOrEqualTo: "shouldBeOverOrEqualTo",
lengthUnder: "shouldBeUnder",
lengthUnderOrEqualTo: "shouldBeUnderOrEqualTo",

over: "shouldBeOver",
overOrEqualTo: "shouldBeOverOrEqualTo",

under: "shouldBeUnder",
underOrEqualTo: "shouldBeUnderOrEqualTo",

including: "shouldInclude"
}
},
"EN-us": { ... }
};
``````

(which is the quick `EN-gb` language that I made)

See above for how to include a language

## Keywords

none

### Install

`npm i yes-sir`

2

1.0.1

MIT

### Repository

github.com/Zoweb/Yes-Sir