Merge pull request #15 from Haberkamp/add-core-package

Add core package

Author: Haberkamp

.changeset/real-sheep-read.md

@@ -0,0 +1,5 @@
+---
+"@typed-storage/core": minor
+---
+
+Add `@typed-storage/core` package

README.md

@@ -13,6 +13,7 @@ Usage does vary depending on the framework you're using.
 
 - [React](./packages/react)
 - Vue (coming soon)
+- [Vanilla JS](./packages/core)
 
 ## Feedback and Contributing
 

packages/core/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nils Haberkamp
+
+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.

packages/core/README.md

@@ -0,0 +1,63 @@
+# @typed-storage/core
+
+![CI passing](https://github.com/Haberkamp/typed-storage/actions/workflows/ci.yml/badge.svg?event=push&branch=main)
+![Created by](https://img.shields.io/badge/created%20by-@n__haberkamp-065afa.svg)
+![NPM License](https://img.shields.io/npm/l/%40typed-storage%2Fcore)
+
+## Highlights
+
+- Schema validation
+- Automatic type inference
+- Use it with zod, validbot, arktype, etc.
+
+## Overview
+
+TypedStorage gives you a type-safe way to access `localStorage`. Moreover, you can use zod or any other schema validation library to make sure your data is always valid.
+
+### Author
+
+Hey, I'm Nils. In my spare time [I write about things I learned](https://www.haberkamp.dev/) or I [create open source packages](https://github.com/Haberkamp), that help me (and hopefully you) to build better apps.
+
+## Usage
+
+Two steps: define your schema and use it like normal localStorage.
+
+1. Define your schema
+
+```ts
+// schema.ts
+
+import { defineStorage } from "@typed-storage/core"
+// Feel free to use any other StandardSchema compatible library
+import { z } from "zod"
+
+const { storage } = defineStorage({
+  theme: z.enum(["light", "dark"]),
+})
+
+export { storage }
+```
+
+2. Use the storage
+
+```ts
+// my-file.ts
+
+import { storage } from "./schema"
+
+storage.set("theme", "light")
+
+const theme = storage.get("theme")
+```
+
+## Installation
+
+You can install this package with any package manager you like.
+
+```bash
+pnpm add @typed-storage/core
+```
+
+## Feedback and Contributing
+
+I highly appreceate your feedback! Please create an [issue](https://github.com/Haberkamp/typed-storage/issues/new), if you've found any bugs or want to request a feature.

packages/core/eslint.config.mjs

@@ -0,0 +1,26 @@
+// @ts-check
+
+import eslint from "@eslint/js"
+import tseslint from "typescript-eslint"
+import eslintPluginUnicorn from "eslint-plugin-unicorn"
+
+/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.Config[]} */
+export default tseslint.config(
+  {
+    ignores: ["dist"],
+  },
+  eslint.configs.recommended,
+  eslintPluginUnicorn.configs.recommended,
+  tseslint.configs.recommendedTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      "unicorn/no-null": "off",
+    },
+  },
+)

packages/core/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@typed-storage/core",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest --typecheck",
+    "test:headless": "vitest run --browser.headless --typecheck",
+    "test:exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
+    "lint": "eslint ./src"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.4",
+    "@eslint/js": "^9.24.0",
+    "@vitest/browser": "3.1.1",
+    "eslint": "^9.24.0",
+    "eslint-plugin-unicorn": "^58.0.0",
+    "playwright": "^1.51.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.1",
+    "vitest": "3.1.1",
+    "zod": "^3.23.8"
+  }
+}

packages/core/src/define-storage.test-d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod"
+import { defineStorage } from "./define-storage.js"
+import { test, assertType } from "vitest"
+
+test("it's not possible to set a value that violates the schema", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someKey: z.string(),
+  })
+
+  // ACT & ASSERT
+  // @ts-expect-error -- Cannot set a value that violates the schema
+  assertType(storage.set("someKey", 1))
+})
+
+test("it's not possible to access a non string key", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someKey: z.string(),
+  })
+
+  // ACT & ASSERT
+  // @ts-expect-error -- Cannot access a non string key
+  assertType(storage.get(1))
+})
+
+test("it's not possible to access a non existent key", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someKey: z.string(),
+  })
+
+  // ACT & ASSERT
+  // @ts-expect-error -- Cannot access a non existent key
+  assertType(storage.get("some-non-existent-key"))
+})
+
+test("the value has a type of string", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someKey: z.string(),
+  })
+
+  // ACT & ASSERT
+  assertType<string | null>(storage.get("someKey"))
+})
+
+test("the value has a type of boolean", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someBooleanKey: z.boolean(),
+  })
+
+  // ACT & ASSERT
+  assertType<boolean | null>(storage.get("someBooleanKey"))
+})
+
+test("the value has a type of number", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someNumberKey: z.number(),
+  })
+
+  // ACT & ASSERT
+  assertType<number | null>(storage.get("someNumberKey"))
+})
+
+test("value must have type of null", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someNumberKey: z.number(),
+  })
+
+  // ACT & ASSERT
+  assertType<number | null>(storage.get("someNumberKey"))
+})
+
+test("returns nothing when removing an item", () => {
+  // ARRANGE
+  const { storage } = defineStorage({
+    someKey: z.string(),
+  })
+
+  // ACT
+  storage.remove("someKey")
+
+  // ASSERT
+  assertType<void>(storage.remove("someKey"))
+})