@jblib/should 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Beck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# jblib should
+
+helpful assertions and conditions for typescript.
+
+```ts
+import { shouldNever } from '@jblib/should'
+
+const obj = {
+  field: in?.thing ?? shouldNever()
+}
+```
+
+fail loudly in conditions that should never be met!

package/package.json

@@ -1,42 +1,41 @@
 {
   "name": "@jblib/should",
-  "version": "0.0.1",
-  "description": "should",
+  "version": "0.0.3",
+  "description": "should, assertions that throw errors when conditions aren't met",
   "type": "module",
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
-  },
   "devDependencies": {
-    "vitest": "catalog:",
-    "typescript": "catalog:",
-    "@jblib/eslint": "workspace:*",
-    "prettier": "catalog:",
-    "tsdown": "catalog:"
+    "prettier": "^3.8.3",
+    "tsdown": "^0.21.10",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "@jblib/eslint": "0.0.3"
   },
   "keywords": [
-    "should"
+    "should",
+    "assert"
   ],
   "author": {
     "name": "Joseph Beck"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "types": "./dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joseph-beck/jblib.git",
     "directory": "packages/should"
   },
   "license": "MIT",
-  "packageManager": "pnpm@10.33.0",
   "exports": {
-    ".": "./src/index.ts",
+    ".": "./dist/index.js",
     "./package.json": "./package.json"
   },
-  "publishConfig": {
-    "exports": {
-      ".": "./dist/index.js",
-      "./package.json": "./package.json"
-    }
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   }
-}
+}

package/src/index.ts

@@ -1,3 +1,3 @@
-import { shouldBeTrue } from './should-be-true.js'
-
-export { shouldBeTrue }
+export { shouldBeFalse } from './should-be-false.js'
+export { shouldBeTrue } from './should-be-true.js'
+export { shouldNever } from './should-never.js'

package/src/should-be-false.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+
+import { shouldBeFalse } from './should-be-false.js'
+
+describe('should be false', () => {
+  it('should not throw for false', () => {
+    expect(() => shouldBeFalse(false)).not.toThrow()
+  })
+
+  it('should throw for true', () => {
+    expect(() => shouldBeFalse(true)).toThrow('should be false, but got true')
+  })
+
+  it('should throw for non-false values', () => {
+    expect(() => shouldBeFalse(123)).toThrow('should be false, but got 123')
+    expect(() => shouldBeFalse('hello')).toThrow('should be false, but got hello')
+    expect(() => shouldBeFalse({})).toThrow('should be false, but got [object Object]')
+    expect(() => shouldBeFalse([])).toThrow('should be false, but got ')
+    expect(() => shouldBeFalse(null)).toThrow('should be false, but got null')
+    expect(() => shouldBeFalse(undefined)).toThrow('should be false, but got undefined')
+  })
+
+  it('should use custom message if provided', () => {
+    expect(() => shouldBeFalse(true, 'custom error message')).toThrow('custom error message')
+  })
+})

package/src/should-be-false.ts

@@ -0,0 +1,15 @@
+/**
+ * shouldBeFalse checks if the provided value is strictly false.
+ * If it is not, it throws an error.
+ *
+ * @param v value that should always be false
+ * @param message custom error message to throw if the value is not false
+ * @throws {Error} if the value is not false
+ */
+const shouldBeFalse = (v: unknown, message?: string): void => {
+  if (v !== false) {
+    throw new Error(message ?? `should be false, but got ${String(v)}`)
+  }
+}
+
+export { shouldBeFalse }

package/src/should-be-true.spec.ts

@@ -3,20 +3,24 @@ import { describe, expect, it } from 'vitest'
 import { shouldBeTrue } from './should-be-true.js'
 
 describe('should be true', () => {
-  it('should return true for true', () => {
-    expect(shouldBeTrue(true)).toBe(true)
+  it('should not throw for true', () => {
+    expect(() => shouldBeTrue(true)).not.toThrow()
   })
 
-  it('should return false for false', () => {
-    expect(shouldBeTrue(false)).toBe(false)
+  it('should throw for false', () => {
+    expect(() => shouldBeTrue(false)).toThrow('should be true, but got false')
   })
 
-  it('should return false for non-true values', () => {
-    expect(shouldBeTrue(123)).toBe(false)
-    expect(shouldBeTrue('hello')).toBe(false)
-    expect(shouldBeTrue({})).toBe(false)
-    expect(shouldBeTrue([])).toBe(false)
-    expect(shouldBeTrue(null)).toBe(false)
-    expect(shouldBeTrue(undefined)).toBe(false)
+  it('should throw for non-true values', () => {
+    expect(() => shouldBeTrue(123)).toThrow('should be true, but got 123')
+    expect(() => shouldBeTrue('hello')).toThrow('should be true, but got hello')
+    expect(() => shouldBeTrue({})).toThrow('should be true, but got [object Object]')
+    expect(() => shouldBeTrue([])).toThrow('should be true, but got ')
+    expect(() => shouldBeTrue(null)).toThrow('should be true, but got null')
+    expect(() => shouldBeTrue(undefined)).toThrow('should be true, but got undefined')
+  })
+
+  it('should use custom message if provided', () => {
+    expect(() => shouldBeTrue(false, 'custom error message')).toThrow('custom error message')
   })
 })

package/src/should-be-true.ts

@@ -1,3 +1,15 @@
-const shouldBeTrue = (v: unknown): boolean => v === true
+/**
+ * shouldBeTrue checks if the provided value is strictly true.
+ * If it is not, it throws an error.
+ *
+ * @param v value that should always be true
+ * @param message custom error message to throw if the value is not true
+ * @throws {Error} if the value is not true
+ */
+const shouldBeTrue = (v: unknown, message?: string): void => {
+  if (v !== true) {
+    throw new Error(message ?? `should be true, but got ${String(v)}`)
+  }
+}
 
 export { shouldBeTrue }

package/src/should-never.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+
+import { shouldNever } from './should-never.js'
+
+describe('should never', () => {
+  it('should always throw', () => {
+    expect(() => shouldNever()).toThrow()
+  })
+})

package/src/should-never.ts

@@ -0,0 +1,12 @@
+/**
+ * shouldNever always throws an error when called.
+ * This is useful for failing in areas that should never be reached.
+ *
+ * @param message custom error message to throw if the value is called
+ * @throws {Error} if the value is called
+ */
+const shouldNever = (message?: string): never => {
+  throw new Error(message ?? 'should never be called')
+}
+
+export { shouldNever }

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-import { shouldBeTrue } from "./should-be-true.js";
-export { shouldBeTrue };

package/dist/index.js

@@ -1,3 +0,0 @@
-import { shouldBeTrue } from "./should-be-true.js";
-
-export { shouldBeTrue };

package/dist/should-be-true.d.ts

@@ -1,5 +0,0 @@
-//#region src/should-be-true.d.ts
-declare const shouldBeTrue: (v: unknown) => boolean;
-//#endregion
-export { shouldBeTrue };
-//# sourceMappingURL=should-be-true.d.ts.map

package/dist/should-be-true.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"should-be-true.d.ts","names":[],"sources":["../src/should-be-true.ts"],"mappings":";cAAM,YAAA,GAAgB,CAAA"}

package/dist/should-be-true.js

@@ -1,6 +0,0 @@
-//#region src/should-be-true.ts
-const shouldBeTrue = (v) => v === true;
-
-//#endregion
-export { shouldBeTrue };
-//# sourceMappingURL=should-be-true.js.map

package/dist/should-be-true.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"should-be-true.js","names":[],"sources":["../src/should-be-true.ts"],"sourcesContent":["const shouldBeTrue = (v: unknown): boolean => v === true\n\nexport { shouldBeTrue }\n"],"mappings":";AAAA,MAAM,gBAAgB,MAAwB,MAAM"}

package/eslint.config.ts

@@ -1,6 +0,0 @@
-import { jblibConfig } from '@jblib/eslint'
-import { type Linter } from 'eslint'
-
-const config: Linter.Config[] = [...jblibConfig]
-
-export default config

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "composite": true,
-    "noEmit": false
-  },
-  "include": ["src", "*.config.ts"]
-}

package/tsdown.config.ts

@@ -1,23 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-export default defineConfig({
-  entry: ['./src/index.ts'],
-  format: ['esm'],
-  platform: 'node',
-  unbundle: true,
-  dts: true,
-  sourcemap: true,
-  clean: true,
-  minify: false,
-  fixedExtension: false,
-  exports: {
-    devExports: true,
-  },
-  publint: {
-    strict: true,
-  },
-  attw: {
-    profile: 'esm-only',
-    level: 'error',
-  },
-})

package/vitest.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    exclude: ['src/**/*.gen.ts'],
-    include: ['src/**/*.spec.ts'],
-  },
-  resolve: {
-    tsconfigPaths: true,
-  },
-})