zerde 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# Zerde
+
+Typescript library for parsing and stringifying combined with schema validationg
+
+When stringifying or parsing an object, you want to verify that what you are stringifying or parsing matches a schema.
+This is the overall workflow:
+Parsing: stringifiedContent -> parse -> SomeObject
+Stringifying: SomeObject -> stringify -> stringifiedContent
+
+However, all type safety is lost during these steps (especially during the parse step)
+
+The desired workflow:
+
+Parsing: stringifiedContent<SomeType> -> parse -> Unknown -> validateIsSomeType -> SomeType
+Stringifying: SomeType -> validateIsSomeType -> stringify -> stringifiedContent<SomeType>
+
+This way, you are able to parse some unknown string into a strongly typed result, and ensure that the object you are about to stringify matches the intended schema
+
+The next step is each `parse`/`stringify` function is specific to one format. `JSON.parse`/`JSON.stringify` only handles `JSON`. What if you need to parse/stringify some other format? Import another library.
+
+This library provides a unified way to parse, stringify and validate:
+
+[x] JSON
+[] YAML (coming soon)
+[] TOML (coming soon)
+[] CSV (coming soon)
+
+Makes use of [Standard Schema](https://github.com/standard-schema/standard-schema) to support all the popular schema libraries (Zod, Valibot, etc).
+
+## Quick Start
+
+```ts
+import { zparse, zstringify } from "zerde"
+import { z } from "zod"
+
+const personSchema = z.object({
+    name: z.string(),
+    age: z.number()
+})
+
+const aPerson = {
+    name: "Some Name",
+    age: 30
+}
+
+// Will check if aPerson matches the personSchema, then stringify the person
+const stringifyResult = await zstringify(aPerson, personSchema)
+//    ^stringifyResult is a neverthrow ResultAsync
+
+if (stringifyResult.isOk()) {
+    const stringifiedPerson = stringifyResult.data
+    //    ^stringifiedPerson is '{"name":"Some Name","age":30}'
+
+    // Will parse the stringifiedPerson, then check if the output matches the personSchema
+    const parseResult = await zparse(stringifiedPerson, personSchema, "JSON")
+    //    ^parseResult is a neverthrow ResultAsync
+    
+    if (parseResult.isOk()) {
+        // This is the same aPerson from before
+        const parsedPerson = parseResult.data
+        
+        assert(aPerson.name === parsedPerson.name)
+        assert(aPerson.age === parsedPerson.age)
+        
+    } else {
+        // this error could have been from parsing, or from validating agains the schema
+        const parseError = parseResult.error
+    }
+    
+} else {
+    // This error could have been from stringifying, or from validating against the schema 
+    const stringifyError = stringifyResult.error
+}
+```
+
+## Specifying a Format
+
+Can provide a format as a string:
+
+```ts
+zparse(someJSONstringifiedString, someSchema, "JSON")
+```
+
+Handles a wide variety of string cases:
+
+| Case | Example |
+| --- | --- |
+| uppercase | "JSON" |
+| lowercase | "json" |
+| mixedcase | "jSoN" |
+| extension | ".json" |
+| file | "file.json" |
+| file with path | "some/path/to/file.json" |
+| file with a windows path | "some\\path\\to\\file.json" |
+| basic media type | "application/json" |
+| complex media type | "application/customFormat+json" |
+| media type with charset | "application/customFormat+json; charset=utf-8" |
+
+
+When calling `zparse`, if the unknownContent was not a string, or if no format is specified, or if the specified format is not supported, `zparse` will not modify the passed in content before validating it. So if you know you are parsing a `JSON.stringify`-ed string, pass `JSON` as the 3rd arg to `zparse`
+
+When calling `zstringify`, if no format is specified, or if the specified format is not supported, `zparse` fall back to assuming the format was `JSON`.
+

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import * as neverthrow0$1 from "neverthrow";
+import * as neverthrow4 from "neverthrow";
+import * as neverthrow0 from "neverthrow";
+import { ResultAsync } from "neverthrow";
+import { ParseOptions as ParseOptions$1 } from "jsonc-parser";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/formats/json.d.ts
+type ParseJSONOptions = Partial<ParseOptions$1>;
+type StringifyJSONOptions = string | number;
+//#endregion
+//#region src/utils.d.ts
+type ErrorInfo<T> = T & {
+  cause: unknown;
+};
+declare class EnhancedError<T = unknown> extends Error {
+  constructor(message: string, info: ErrorInfo<T>);
+}
+//#endregion
+//#region src/parse.d.ts
+declare class ParseError extends EnhancedError {}
+type ParseOptions = {
+  json: ParseJSONOptions;
+};
+declare const defaultParseOptions: {
+  readonly json: {
+    readonly allowEmptyContent: true;
+    readonly allowTrailingComma: true;
+    readonly disallowComments: true;
+  };
+};
+declare const parseIt: (stringifiedContent: string, formatAndParseOptions: Partial<ParseOptions & {
+  format: string;
+}>) => neverthrow0$1.Result<unknown, ParseError>;
+//#endregion
+//#region src/stringify.d.ts
+declare class StringifyError extends EnhancedError {}
+type StringifyOptions = {
+  json: StringifyJSONOptions;
+};
+declare const defaultStringifyOptions: {
+  readonly json: 0;
+};
+declare const stringifyIt: (unknownContent: unknown, formatAndStringifyOptions: Partial<StringifyOptions & {
+  format: string;
+}>) => neverthrow4.Result<string, StringifyError>;
+//#endregion
+//#region src/typeHelpers.d.ts
+type ObjectKeys<T extends object> = `${Exclude<keyof T, symbol>}`;
+declare const objectKeys: <Type extends Record<string, unknown>>(value: Type) => Array<ObjectKeys<Type>>;
+declare const objectEntries: <Type extends Record<string, unknown>>(value: Type) => Array<[ObjectKeys<Type>, Required<Type>[ObjectKeys<Type>]]>;
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+//#endregion
+//#region src/validate.d.ts
+declare class ValidationError extends EnhancedError {
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+declare const validateIt: <Schema extends StandardSchemaV1>(unknownContent: unknown, schema: Schema) => ResultAsync<unknown, ValidationError>;
+//#endregion
+//#region src/zerde.d.ts
+type ZerdeOptions = Partial<{
+  parse: ParseOptions;
+  stringify: StringifyOptions;
+}>;
+declare class Zerde {
+  parseOptions: {
+    readonly json: {
+      readonly allowEmptyContent: true;
+      readonly allowTrailingComma: true;
+      readonly disallowComments: true;
+    };
+  };
+  stringifyOptions: {
+    readonly json: 0;
+  };
+  constructor(options?: ZerdeOptions);
+  parse: <Schema extends StandardSchemaV1>(unknownContent: unknown, schema: Schema, parseOptions?: string | Partial<ParseOptions>) => neverthrow0.ResultAsync<unknown, ParseError | ValidationError>;
+  stringify: <Schema extends StandardSchemaV1>(unknownContent: unknown, schema: Schema, stringifyOptions?: string | Partial<StringifyOptions>) => neverthrow0.ResultAsync<string, ValidationError | StringifyError>;
+}
+declare const zerde: Zerde;
+declare const zparse: <Schema extends StandardSchemaV1>(unknownContent: unknown, schema: Schema, parseOptions?: string | Partial<ParseOptions>) => neverthrow0.ResultAsync<unknown, ParseError | ValidationError>;
+declare const zstringify: <Schema extends StandardSchemaV1>(unknownContent: unknown, schema: Schema, stringifyOptions?: string | Partial<StringifyOptions>) => neverthrow0.ResultAsync<string, ValidationError | StringifyError>;
+//#endregion
+export { EnhancedError, type ErrorInfo, ParseError, type ParseOptions, Prettify, StringifyError, type StringifyOptions, ValidationError, Zerde, type ZerdeOptions, defaultParseOptions, defaultStringifyOptions, objectEntries, objectKeys, parseIt, stringifyIt, validateIt, zerde, zparse, zstringify };

package/dist/index.js

@@ -0,0 +1 @@
+import{ResultAsync as e,fromThrowable as t}from"neverthrow";import{parse as n}from"jsonc-parser";import{configure as r}from"safe-stable-stringify";const i={allowEmptyContent:!0,allowTrailingComma:!0,disallowComments:!0};function a(e,t={}){let r={...t,...i},a=[],o=n(e,a,r);if(a.length>0)throw SyntaxError(`Could not parse JSON`,{cause:a});return o}const o=0,s=r({bigint:!1,circularValue:SyntaxError,deterministic:!0,strict:!0});function c(e,t){let n=s(e,null,t);if(n===void 0)throw SyntaxError(`safe-stable-stringify should have thrown an error if trying to stringify an invalid json object`);return n}const l=Object.keys,u=Object.entries;var d=class extends Error{constructor(e,t){super(e,{cause:t.cause}),this.name=this.constructor.name}};const f=[`.`,`/`,`\\`,`+`];function p(e){let t=e.trim().toLowerCase();if(!t)return t;let n=t.indexOf(`;`);n>0&&(t=t.slice(0,n));let r=Math.max(...f.map(e=>t.lastIndexOf(e)));return r<0?t:t.slice(r+1)}if(import.meta.vitest){let{describe:e,it:t,expect:n}=import.meta.vitest,r={lowercase:`json`,uppercase:`JSON`,mixedcase:`jSoN`,extension:`.json`,file:`file.json`,"file with path":`some/path/to/file.json`,"file with a windows path":`some\\path\\to\\file.json`,"basic media type":`application/json`,"complex media type":`application/customFormat+json`,"media type with charset":`application/customFormat+json; charset=utf-8`};e(`extractFormatSuffix`,()=>{for(let[e,i]of u(r)){let r=`Can handle ${e}: ${i}`;t(r,()=>{n(p(i)).toEqual(`json`)})}})}var m=class extends d{};const h={json:i},g=t((e,t)=>{let{format:n,...r}=t,i=p(n??``);return i===`json`?a(e,r.json):e},e=>new m(`Could not parse content`,{cause:e}));var _=class extends d{};const v={json:o},y=t((e,t)=>{if(typeof e==`string`)return e;let{format:n,...r}=t,i=p(n??``);return c(e,r.json)},e=>new _(`Could not stringify content`,{cause:e}));var b=class extends d{issues;constructor(e){super(`Content was not valid`,{cause:e}),this.issues=e}};const x=e.fromThrowable(async(e,t)=>{let n=await t[`~standard`].validate(e);if(n.issues)throw new b(n.issues);return n.value},e=>e);var S=class{parseOptions=h;stringifyOptions=v;constructor(e={}){this.parseOptions={...e.parse,...h}}parse=(e,t,n)=>{if(typeof e==`string`){let r=typeof n==`string`?{format:n}:n,i={...this.parseOptions,...r};return g(e,i).asyncAndThen(e=>x(e,t))}return x(e,t)};stringify=(e,t,n)=>{let r=typeof n==`string`?{format:n}:n,i={...this.stringifyOptions,...r};return x(e,t).andThen(e=>y(e,i))}};const C=new S,w=C.parse,T=C.stringify;export{d as EnhancedError,m as ParseError,_ as StringifyError,b as ValidationError,S as Zerde,h as defaultParseOptions,v as defaultStringifyOptions,u as objectEntries,l as objectKeys,g as parseIt,y as stringifyIt,x as validateIt,C as zerde,w as zparse,T as zstringify};

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "zerde",
+    "version": "0.1.0",
+    "description": "parsing, and stringifying combined with schema validation",
+    "keywords": [
+        "parse",
+        "stringify",
+        "validate",
+        "validation",
+        "schema"
+    ],
+    "repository": "github:dannywexler/zerde",
+    "author": "Danny Wexler",
+    "license": "MIT",
+    "type": "module",
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "devDependencies": {
+        "@biomejs/biome": "2.2.6",
+        "lefthook": "^1.13.6",
+        "tsdown": "^0.12.9",
+        "typescript": "^5.9.3",
+        "vite-tsconfig-paths": "^5.1.4",
+        "vitest": "^3.2.4"
+    },
+    "scripts": {
+        "build": "lefthook run build",
+        "lint": "biome check --error-on-warnings --colors=force --write src",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "jsonc-parser": "^3.3.1",
+        "neverthrow": "^8.2.0",
+        "safe-stable-stringify": "^2.5.0"
+    }
+}