{"id":12244,"library":"typescript-nullable","title":"TypeScript Nullable","description":"typescript-nullable is a utility library for TypeScript that formalizes the concept of possibly absent values, providing a type-safe and functional approach to handling `null` and `undefined`. It defines a `Nullable<T>` type, which is explicitly `T | null | undefined`, mirroring the `Maybe` type found in functional languages like Haskell or Elm. Beyond the type definition, the library exports a `Nullable` object containing a suite of utility functions designed to interact safely with these potentially absent values. These functions, such as `map`, `withDefault`, `isNone`, and `isSome`, are curried and pure, promoting a functional programming style and enhancing type safety by leveraging TypeScript's type guards. As of version 0.6.0, the library is actively maintained, with incremental updates focusing on API refinements and feature additions, though a specific release cadence is not formally published. Its core value proposition lies in enabling developers to write more resilient code by explicitly managing the presence or absence of values, thereby reducing runtime errors associated with unexpected `null` or `undefined` references and offering a robust alternative to imperative null checks.","status":"active","version":"0.6.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/kylecorbelli/typescript-nullable","tags":["javascript","TypeScript","Nullable","Maybe","Monad","typescript"],"install":[{"cmd":"npm install typescript-nullable","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-nullable","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-nullable","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This named import provides both the `Nullable<T>` type for type annotations and the `Nullable` object that contains all utility functions.","symbol":"Nullable","correct":"import { Nullable } from 'typescript-nullable';"},{"note":"Utility functions like `isSome`, `map`, and `withDefault` are properties of the imported `Nullable` object, not direct named exports from the package root.","wrong":"import { isSome } from 'typescript-nullable';","symbol":"Nullable object functions","correct":"import { Nullable } from 'typescript-nullable';\nNullable.isSome(value);"},{"note":"The `None` type is an internal type alias (`null | undefined`) used in the definition of `Nullable<T>` and is not directly exported for import. You should define it locally if needed, or use `null | undefined` directly.","wrong":"import { None } from 'typescript-nullable';","symbol":"None","correct":"type None = null | undefined;"}],"quickstart":{"code":"import { Nullable } from 'typescript-nullable';\n\n// Demonstrate Nullable type definition implicitly\ntype UserName = Nullable<string>;\n\nconst userName1: UserName = 'Alice';\nconst userName2: UserName = null;\nconst userName3: UserName = undefined;\n\nconsole.log(`User Name 1: ${userName1}`);\nconsole.log(`User Name 2: ${userName2}`);\nconsole.log(`User Name 3: ${userName3}`);\n\n// Demonstrate utility functions\nconst toUpperCase = (text: string) => text.toUpperCase();\n\n// Nullable.map - example with curried usage\nconst mappedName1 = Nullable.map(toUpperCase)(userName1);\nconst mappedName2 = Nullable.map(toUpperCase)(userName2);\nconsole.log(`Mapped Name 1: ${mappedName1}`);\nconsole.log(`Mapped Name 2: ${mappedName2}`);\n\n// Nullable.withDefault\nconst displayName1 = Nullable.withDefault('Guest')(userName1);\nconst displayName2 = Nullable.withDefault('Guest')(userName2);\nconsole.log(`Display Name 1: ${displayName1}`);\nconsole.log(`Display Name 2: ${displayName2}`);\n\n// Nullable.isSome and Nullable.isNone with TypeScript type guards\nconst potentiallyNullString: Nullable<string> = Math.random() > 0.5 ? 'Hello' : null;\n\nif (Nullable.isSome(potentiallyNullString)) {\n  console.log(`Value is present: ${potentiallyNullString.length}`); // TS knows it's a string here\n} else {\n  console.log('Value is absent.'); // TS knows it's null | undefined here\n}\n\n// Explicit currying example\nconst mapToUpper = Nullable.map(toUpperCase);\nconsole.log(`Curried map result: ${mapToUpper('world')}`);\nconsole.log(`Curried map result (null): ${mapToUpper(null)}`);","lang":"typescript","description":"This quickstart demonstrates the core `Nullable<T>` type definition and shows how to use key utility functions like `map`, `withDefault`, `isSome`, and `isNone` with examples of currying and TypeScript type guards for safe null handling."},"warnings":[{"fix":"Always pin to exact versions (e.g., `\"typescript-nullable\": \"~0.6.0\"` or `\"^0.6.0\"` carefully) and review release notes for any new updates.","message":"The library is currently in version 0.x.x, indicating that the API might not be stable. Expect potential breaking changes in minor or even patch releases before a 1.0.0 release.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure you call curried functions correctly, either by providing all arguments at once (e.g., `Nullable.map(func, value)`) or by explicitly chaining calls (e.g., `Nullable.map(func)(value)`).","message":"All utility functions are curried, meaning they can be called with arguments one at a time, returning new functions until all arguments are satisfied. Forgetting this pattern can lead to unexpected `TypeError`s.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Be mindful that `Nullable` refers to both the type and the value-level object. TypeScript handles this distinction correctly in most contexts, but avoid shadowing or ambiguous variable names.","message":"The `Nullable` symbol is used for both the `Nullable<T>` type and the `Nullable` object containing utility functions. While convenient in TypeScript, it can be confusing if you expect them to be separate imports or if migrating from languages with distinct type/value namespaces.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Utility functions are properties of the `Nullable` object. Import `Nullable` and then access the functions: `import { Nullable } from 'typescript-nullable'; Nullable.isSome(value);`","cause":"Attempting to import utility functions (like `isSome`, `map`, `withDefault`) directly from the package.","error":"TS2305: Module '\"typescript-nullable\"' has no exported member 'isSome'."},{"fix":"Ensure you are using `import { Nullable } from 'typescript-nullable';` for ESM environments. If in CommonJS, try `const { Nullable } = require('typescript-nullable');` or `const Nullable = require('typescript-nullable').Nullable;`","cause":"This usually happens when `Nullable` is not imported correctly, or when using CommonJS `require` without properly handling the ES module interop, leading to `Nullable` being `undefined` or an unexpected object.","error":"TypeError: Nullable.map is not a function"},{"fix":"The `None` type is an internal alias for `null | undefined` and is not exported. You should use `null | undefined` directly or define your own `type None = null | undefined;` if you wish to use that alias in your code.","cause":"Attempting to import the `None` type alias directly from the package.","error":"TS2305: Module '\"typescript-nullable\"' has no exported member 'None'."}],"ecosystem":"npm"}