yes-sir v1.0.1

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: 1. Download it off the website 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