@buildinams/core 0.2.0 → 0.3.1

package/dist/chunk-5KDGGGVO.js

@@ -0,0 +1,40 @@
+// src/schema/schema.ts
+var createSchema = (template) => ({
+  ...template,
+  parserialize: (value, next) => {
+    return template.serialize(next(template.parse(value)));
+  }
+});
+
+// src/schema/string-schema.ts
+var createStringSchema = (template) => {
+  const schema = createSchema({
+    serialize: template.stringify,
+    parse: template.parse
+  });
+  return {
+    parse: schema.parse,
+    stringify: schema.serialize,
+    parseStringify: schema.parserialize
+  };
+};
+
+// src/schema/href-schema.ts
+var hrefSchema = createStringSchema({
+  parse: (href) => {
+    const [pathname = "", search = ""] = href.split("?");
+    return {
+      pathname,
+      searchParams: new URLSearchParams(search)
+    };
+  },
+  stringify: (state) => {
+    if (!state.searchParams) return state.pathname;
+    const paramsString = state.searchParams.toString();
+    return state.pathname + (paramsString ? `?${paramsString}` : "");
+  }
+});
+
+export { createSchema, createStringSchema, hrefSchema };
+//# sourceMappingURL=chunk-5KDGGGVO.js.map
+//# sourceMappingURL=chunk-5KDGGGVO.js.map

package/dist/chunk-5KDGGGVO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/schema.ts","../src/schema/string-schema.ts","../src/schema/href-schema.ts"],"names":[],"mappings":";AAkGO,IAAM,YAAA,GAAe,CAK3B,QAAA,MACmD;AAAA,EACnD,GAAG,QAAA;AAAA,EAEH,YAAA,EAAc,CAAC,KAAA,EAAO,IAAA,KAAS;AAC9B,IAAA,OAAO,SAAS,SAAA,CAAU,IAAA,CAAK,SAAS,KAAA,CAAM,KAAK,CAAC,CAAC,CAAA;AAAA,EACtD;AACD,CAAA;;;AC9FO,IAAM,kBAAA,GAAqB,CACjC,QAAA,KAC4C;AAC5C,EAAA,MAAM,SAAS,YAAA,CAA+C;AAAA,IAC7D,WAAW,QAAA,CAAS,SAAA;AAAA,IACpB,OAAO,QAAA,CAAS;AAAA,GAChB,CAAA;AAED,EAAA,OAAO;AAAA,IACN,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,WAAW,MAAA,CAAO,SAAA;AAAA,IAClB,gBAAgB,MAAA,CAAO;AAAA,GACxB;AACD;;;ACKO,IAAM,aAAa,kBAAA,CASxB;AAAA,EACD,KAAA,EAAO,CAAC,IAAA,KAAS;AAChB,IAAA,MAAM,CAAC,WAAW,EAAA,EAAI,MAAA,GAAS,EAAE,CAAA,GAAI,IAAA,CAAK,MAAM,GAAG,CAAA;AACnD,IAAA,OAAO;AAAA,MACN,QAAA;AAAA,MACA,YAAA,EAAc,IAAI,eAAA,CAAgB,MAAM;AAAA,KACzC;AAAA,EACD,CAAA;AAAA,EACA,SAAA,EAAW,CAAC,KAAA,KAAU;AACrB,IAAA,IAAI,CAAC,KAAA,CAAM,YAAA,EAAc,OAAO,KAAA,CAAM,QAAA;AACtC,IAAA,MAAM,YAAA,GAAe,KAAA,CAAM,YAAA,CAAa,QAAA,EAAS;AACjD,IAAA,OAAO,KAAA,CAAM,QAAA,IAAY,YAAA,GAAe,CAAA,CAAA,EAAI,YAAY,CAAA,CAAA,GAAK,EAAA,CAAA;AAAA,EAC9D;AACD,CAAC","file":"chunk-5KDGGGVO.js","sourcesContent":["/**\n * Defines the schema for parsing and stringifying states to and from primitive values.\n *\n * The `Schema` type is a generic type that takes:\n * - `State`: A state object type.\n * - `Serialized`: The raw value type\n * - `SerializableState?`: (optional) A (partial) state object type that can be used for serialization. Defaults to `State` if not provided.\n *\n * It returns the following methods:\n * - `parse`: A function that takes a raw value and returns the corresponding state object.\n * - `serialize`: A function that takes a (serializable) state object and returns a raw value that represents the given state.\n * - `parserialize`: A function that takes a raw value and a reducer function - it returns a new raw value that represents the reduced state.\n *\n * @see createSchema for a helper function to create a `Schema` from simpler parsing and serializing functions.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type Schema<State = any, Serialized = any, SerializableState = State> = {\n\t/** Parse a raw value into the state shape */\n\tparse: (value: Serialized) => State;\n\t/** Serialize a state shape into a raw value */\n\tserialize: (state: SerializableState) => Serialized;\n\n\t/** Compute a new serialized value based on a given serialized value and a reducer of the current state. */\n\tparserialize: (\n\t\tvalue: Serialized,\n\t\tnext: (state: State) => SerializableState,\n\t) => Serialized;\n};\n\n/**\n * A utility type to extract the state shape from a given `Schema`.\n */\nexport type SchemaState<T extends Schema> =\n\tT extends Schema<infer U> ? U : never;\n\n/**\n * A utility type to extract the serialized value type from a given `Schema`.\n */\nexport type SchemaSerialized<T extends Schema> =\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends Schema<any, infer U> ? U : never;\n\n/**\n * A utility type to extract the serializable state shape from a given `Schema`.\n */\nexport type SchemaSerializableState<T extends Schema> =\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends Schema<any, any, infer U> ? U : never;\n\n/**\n * Low-level helper function to create a basic `Schema` that receives the config for converting between serialized values and state objects.\n *\n * The template requires two methods:\n * - `parse`: A method that takes a serialized value and returns the corresponding state object.\n * - `serialize`: A method that takes a state object and returns a serialized value that represents the given state.\n *\n * The `parserialize` method is automatically implemented based on the provided `parse` and `serialize` methods, allowing you to compute a new serialized value based on an existing serialized value and a reducer function for the state.\n *\n * @example\n * ```ts\n * import { createSchema } from \"@buildinams/core/schema\";\n *\n * const numberSchema = createSchema<\n *   number, // State\n *   string // Serialized\n * >({\n *   parse: (value) => parseInt(value, 10),\n *   serialize: (state) => state.toString(),\n * });\n *\n * const result = numberSchema.parserialize(\"42\", (state) => state + 1);\n * console.log(result); // \"43\"\n * ```\n *\n * @example\n * ```ts\n * import { createSchema } from \"@buildinams/core/schema\";\n *\n * const hrefSchema: createSchema<\n *   { pathname: string, searchParams: URLSearchParams },\n *   string,\n *   { pathname: string, searchParams?: URLSearchParams } // SerializableState allows to define different state used for serialization, in this case making searchParams optional to allow for more flexible stringification logic\n * >({\n *  parse: (href) => {\n *    const [pathname = \"\", search = \"\"] = href.split(\"?\");\n *    return {\n *     pathname,\n *     searchParams: new URLSearchParams(search),\n *    };\n *  },\n *  serialize: (serializableState) => {\n *    if (!serializableState.searchParams) return serializableState.pathname;\n *    const paramsString = serializableState.searchParams.toString();\n *    return serializableState.pathname + (paramsString ? `?${paramsString}` : \"\");\n *  },\n * })\n * ```\n */\nexport const createSchema = <\n\tState = never,\n\tSerialized = never,\n\tSerializableState = State,\n>(\n\ttemplate: Omit<Schema<State, Serialized, SerializableState>, \"parserialize\">,\n): Schema<State, Serialized, SerializableState> => ({\n\t...template,\n\n\tparserialize: (value, next) => {\n\t\treturn template.serialize(next(template.parse(value)));\n\t},\n});\n","import type { Schema } from \"./schema\";\nimport { createSchema } from \"./schema\";\n\nexport type StringSchema<State = never, SerializableState = State> = {\n\tparse: Schema<State, string, SerializableState>[\"parse\"];\n\tstringify: Schema<State, string, SerializableState>[\"serialize\"];\n\tparseStringify: Schema<State, string, SerializableState>[\"parserialize\"];\n};\n\n/**\n * Helper function to create a `StringSchema` which converts between strings and state objects.\n *\n * The template requires two functions:\n * - `parse`: A function that takes a string and returns the corresponding state object.\n * - `stringify`: A function that takes a state object and returns a string that represents the given state.\n */\nexport const createStringSchema = <State = never, SerializableState = State>(\n\ttemplate: Omit<StringSchema<State, SerializableState>, \"parseStringify\">,\n): StringSchema<State, SerializableState> => {\n\tconst schema = createSchema<State, string, SerializableState>({\n\t\tserialize: template.stringify,\n\t\tparse: template.parse,\n\t});\n\n\treturn {\n\t\tparse: schema.parse,\n\t\tstringify: schema.serialize,\n\t\tparseStringify: schema.parserialize,\n\t};\n};\n","import { createStringSchema } from \"./string-schema\";\n\n/**\n * Utility schema for parsing and stringifying href strings into structured state objects that include the pathname and URL search parameters.\n *\n *  @example\n * ```ts\n * import { createSchema, hrefSchema } from \"@buildinams/core/schema\";\n *\n * const myHrefSchema = createSchema<{\n *  page: number,\n *  // Used to compute next href - don't use directly. Use `.stringify()` instead\n *  _href: string\n * }>({\n *   parse: (href) => {\n *    const { searchParams } = hrefSchema.parse(href);\n *    return {\n *     page: parseInt(searchParams.get(\"page\") || \"1\", 10),\n *     _href: href,\n *    }\n *   },\n *   serialize: (state) => {\n *    const { pathname, searchParams } = hrefSchema.parse(state._href);\n *    searchParams.delete(\"page\");\n *    if (state.page > 1) {\n *     searchParams.set(\"page\", state.page.toString());\n *    }\n *\n *    // note that `searchParams` are optional for serialization\n *    return hrefSchema.stringify({ pathname, searchParams });\n *   }\n * });\n * ```\n */\nexport const hrefSchema = createStringSchema<\n\t{\n\t\tpathname: string;\n\t\tsearchParams: URLSearchParams;\n\t},\n\t{\n\t\tpathname: string;\n\t\tsearchParams?: URLSearchParams;\n\t}\n>({\n\tparse: (href) => {\n\t\tconst [pathname = \"\", search = \"\"] = href.split(\"?\");\n\t\treturn {\n\t\t\tpathname,\n\t\t\tsearchParams: new URLSearchParams(search),\n\t\t};\n\t},\n\tstringify: (state) => {\n\t\tif (!state.searchParams) return state.pathname;\n\t\tconst paramsString = state.searchParams.toString();\n\t\treturn state.pathname + (paramsString ? `?${paramsString}` : \"\");\n\t},\n});\n"]}

package/dist/navigation/index.d.ts

@@ -1,33 +1,21 @@
-/**
- * Defines the schema for parsing and stringifying states to and from hrefs.
- *
- * The `HrefSchema` type is a generic that takes a state shape and declares three methods:
- *
- * - `parse`: A function that takes an href string and returns the corresponding state object.
- * - `stringify`: A function that takes a state object and the current href, and returns a new href string that represents the given state.
- * - `parseStringify`: A function that takes a current href and a mutation function, and returns a new href string that represents the mutated state.
- *
- * This schema is used to map application state to URL hrefs and vice versa.
- */
-type HrefSchema<State = any> = {
+import { S as Schema } from '../schema-CfQvhbuU.js';
+
+/** @deprecated use `Schema` directly */
+type HrefSchema<State = never> = {
     /** Parse a href string into the state shape */
-    parse: (href: string) => State & {
+    parse: Schema<State & {
         href: string;
-    };
-    /** Stringify a state shape and current href into a new href string */
-    stringify: (state: State & {
+    }, string>["parse"];
+    /** Stringify a state shape into a href string */
+    stringify: Schema<State & {
+        href: string;
+    }, string>["serialize"];
+    /** Compute a new href string based on a given href string and a reducer of the current state. */
+    parseStringify: Schema<State & {
         href: string;
-    }) => string;
-    /** Compute a new href string based on a given href and a mutation of the current state. */
-    parseStringify: (href: string, mutate: (state: State) => State) => string;
-    /**
-     * @internal
-     */
-    _template: HrefSchemaTemplate<State>;
+    }, string>["parserialize"];
 };
-/**
- * A utility type to extract the state shape from a given `HrefSchema`. It infers the state type from the `HrefSchema` and adds the `href` property to it.
- */
+/** @deprecated use `SchemaState` directly */
 type HrefSchemaState<T extends HrefSchema> = T extends HrefSchema<infer U> ? U & {
     href: string;
 } : never;
@@ -39,6 +27,38 @@ type HrefSchemaState<T extends HrefSchema> = T extends HrefSchema<infer U> ? U &
  * - `stateToUrl`: A function that takes a state object and the current URL, and returns a new URL object that represents the given state.
  *
  * This allows you to focus on the logic for how your application's state maps to the URL structure without having to manually handle the parsing and stringifying of hrefs.
+ *
+ * @deprecated The `createHrefSchema` function is deprecated in favor of using the more flexible `createStringSchema` function directly with custom parsing and stringifying logic. The `createStringSchema` function can be used to achieve the same functionality without being tied specifically to hrefs, allowing for greater reuse and adaptability in different contexts.
+ *
+ * @example
+ * ```ts
+ * import { createHrefSchema } from "@buildinams/core/schema";
+ *
+ * const myHrefSchema = createHrefSchema<{
+ *  page: number,
+ * }>({
+ *   urlToState: (url) => {
+ *    return {
+ *     page: parseInt(url.searchParams.get("page") || "1", 10),
+ *    }
+ *   },
+ *   stateToUrl: (state, url) => {
+ *    url.searchParams.delete("page");
+ *    if (state.page > 1) {
+ *      url.searchParams.set("page", state.page.toString());
+ *    }
+ *    return url;
+ *   }
+ * });
+ *
+ * // Using the schema to parse a href string into state
+ * const state = myHrefSchema.parse("/products?page=2");
+ * console.log(state); // { page: 2, href: "/products?page=2" }
+ *
+ * // Using the schema to stringify a state object into a href string
+ * const href = myHrefSchema.stringify({ page: 3, href: "/products?page=2" });
+ * console.log(href); // "/products?page=3"
+ * ```
  */
 declare const createHrefSchema: <T>(template: HrefSchemaTemplate<T>) => HrefSchema<T>;
 type HrefSchemaTemplate<State = never> = {

package/dist/navigation/index.js

@@ -1,7 +1,8 @@
+import { createStringSchema } from '../chunk-5KDGGGVO.js';
+
 // src/navigation/href-schema.ts
 var hrefToUrl = (href) => new URL(href, "http://localhost");
-var createHrefSchema = (template) => ({
-  _template: template,
+var createHrefSchema = (template) => createStringSchema({
   stringify: (state) => {
     const current = hrefToUrl(state.href);
     const next = template.stateToUrl(state, current);
@@ -13,14 +14,6 @@ var createHrefSchema = (template) => ({
       ...template.urlToState(current),
       href: current.pathname + current.search
     };
-  },
-  parseStringify: (href, mutate) => {
-    const current = hrefToUrl(href);
-    const next = template.stateToUrl(
-      mutate(template.urlToState(current)),
-      current
-    );
-    return next.pathname + next.search;
   }
 });
 

package/dist/navigation/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/navigation/href-schema.ts"],"names":[],"mappings":";AAmCA,IAAM,YAAY,CAAC,IAAA,KAAiB,IAAI,GAAA,CAAI,MAAM,kBAAkB,CAAA;AAW7D,IAAM,gBAAA,GAAmB,CAC/B,QAAA,MACoB;AAAA,EACpB,SAAA,EAAW,QAAA;AAAA,EACX,SAAA,EAAW,CAAC,KAAA,KAAU;AACrB,IAAA,MAAM,OAAA,GAAU,SAAA,CAAU,KAAA,CAAM,IAAI,CAAA;AACpC,IAAA,MAAM,IAAA,GAAO,QAAA,CAAS,UAAA,CAAW,KAAA,EAAO,OAAO,CAAA;AAC/C,IAAA,OAAO,IAAA,CAAK,WAAW,IAAA,CAAK,MAAA;AAAA,EAC7B,CAAA;AAAA,EAEA,KAAA,EAAO,CAAC,IAAA,KAAS;AAChB,IAAA,MAAM,OAAA,GAAU,UAAU,IAAI,CAAA;AAC9B,IAAA,OAAO;AAAA,MACN,GAAG,QAAA,CAAS,UAAA,CAAW,OAAO,CAAA;AAAA,MAC9B,IAAA,EAAM,OAAA,CAAQ,QAAA,GAAW,OAAA,CAAQ;AAAA,KAClC;AAAA,EACD,CAAA;AAAA,EAEA,cAAA,EAAgB,CAAC,IAAA,EAAM,MAAA,KAAW;AACjC,IAAA,MAAM,OAAA,GAAU,UAAU,IAAI,CAAA;AAC9B,IAAA,MAAM,OAAO,QAAA,CAAS,UAAA;AAAA,MACrB,MAAA,CAAO,QAAA,CAAS,UAAA,CAAW,OAAO,CAAC,CAAA;AAAA,MACnC;AAAA,KACD;AACA,IAAA,OAAO,IAAA,CAAK,WAAW,IAAA,CAAK,MAAA;AAAA,EAC7B;AACD,CAAA","file":"index.js","sourcesContent":["/**\n * Defines the schema for parsing and stringifying states to and from hrefs.\n *\n * The `HrefSchema` type is a generic that takes a state shape and declares three methods:\n *\n * - `parse`: A function that takes an href string and returns the corresponding state object.\n * - `stringify`: A function that takes a state object and the current href, and returns a new href string that represents the given state.\n * - `parseStringify`: A function that takes a current href and a mutation function, and returns a new href string that represents the mutated state.\n *\n * This schema is used to map application state to URL hrefs and vice versa.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type HrefSchema<State = any> = {\n\t/** Parse a href string into the state shape */\n\tparse: (href: string) => State & { href: string };\n\t/** Stringify a state shape and current href into a new href string */\n\tstringify: (state: State & { href: string }) => string;\n\n\t/** Compute a new href string based on a given href and a mutation of the current state. */\n\tparseStringify: (href: string, mutate: (state: State) => State) => string;\n\n\t/**\n\t * @internal\n\t */\n\t_template: HrefSchemaTemplate<State>;\n};\n\n/**\n * A utility type to extract the state shape from a given `HrefSchema`. It infers the state type from the `HrefSchema` and adds the `href` property to it.\n */\nexport type HrefSchemaState<T extends HrefSchema> =\n\tT extends HrefSchema<infer U> ? U & { href: string } : never;\n\n// This is fine as we only use the `pathname` an `search` properties from the URL object,\n// which do not contain the \"https://localhost\" origin.\nconst hrefToUrl = (href: string) => new URL(href, \"http://localhost\");\n\n/**\n * Helper function to create a `HrefSchema` from a simpler template that only requires the logic for converting between URLs and state objects. The `createSchema` function takes care of implementing the `parse`, `stringify`, and `parseStringify` methods based on the provided template functions.\n *\n * The template requires two functions:\n * - `urlToState`: A function that takes a URL object and returns the corresponding state object.\n * - `stateToUrl`: A function that takes a state object and the current URL, and returns a new URL object that represents the given state.\n *\n * This allows you to focus on the logic for how your application's state maps to the URL structure without having to manually handle the parsing and stringifying of hrefs.\n */\nexport const createHrefSchema = <T>(\n\ttemplate: HrefSchemaTemplate<T>,\n): HrefSchema<T> => ({\n\t_template: template,\n\tstringify: (state) => {\n\t\tconst current = hrefToUrl(state.href);\n\t\tconst next = template.stateToUrl(state, current);\n\t\treturn next.pathname + next.search;\n\t},\n\n\tparse: (href) => {\n\t\tconst current = hrefToUrl(href);\n\t\treturn {\n\t\t\t...template.urlToState(current),\n\t\t\thref: current.pathname + current.search,\n\t\t};\n\t},\n\n\tparseStringify: (href, mutate) => {\n\t\tconst current = hrefToUrl(href);\n\t\tconst next = template.stateToUrl(\n\t\t\tmutate(template.urlToState(current)),\n\t\t\tcurrent,\n\t\t);\n\t\treturn next.pathname + next.search;\n\t},\n});\n\ntype HrefSchemaTemplate<State = never> = {\n\t/** Parse a href string into the state shape */\n\turlToState: (url: URL) => State;\n\t/** Stringify a state shape and current href into a new href string */\n\tstateToUrl: (state: State, url: URL) => URL;\n};\n"]}
+{"version":3,"sources":["../../src/navigation/href-schema.ts"],"names":[],"mappings":";;;AAMA,IAAM,YAAY,CAAC,IAAA,KAAiB,IAAI,GAAA,CAAI,MAAM,kBAAkB,CAAA;AAyD7D,IAAM,gBAAA,GAAmB,CAC/B,QAAA,KAEA,kBAAA,CAAyC;AAAA,EACxC,SAAA,EAAW,CAAC,KAAA,KAAU;AACrB,IAAA,MAAM,OAAA,GAAU,SAAA,CAAU,KAAA,CAAM,IAAI,CAAA;AACpC,IAAA,MAAM,IAAA,GAAO,QAAA,CAAS,UAAA,CAAW,KAAA,EAAO,OAAO,CAAA;AAC/C,IAAA,OAAO,IAAA,CAAK,WAAW,IAAA,CAAK,MAAA;AAAA,EAC7B,CAAA;AAAA,EAEA,KAAA,EAAO,CAAC,IAAA,KAAS;AAChB,IAAA,MAAM,OAAA,GAAU,UAAU,IAAI,CAAA;AAC9B,IAAA,OAAO;AAAA,MACN,GAAG,QAAA,CAAS,UAAA,CAAW,OAAO,CAAA;AAAA,MAC9B,IAAA,EAAM,OAAA,CAAQ,QAAA,GAAW,OAAA,CAAQ;AAAA,KAClC;AAAA,EACD;AACD,CAAC","file":"index.js","sourcesContent":["// This is fine as we only use the `pathname` an `search` properties from the URL object,\n\nimport type { Schema } from \"../schema\";\nimport { createStringSchema } from \"../schema\";\n\n// which do not contain the \"https://localhost\" origin.\nconst hrefToUrl = (href: string) => new URL(href, \"http://localhost\");\n\n/** @deprecated use `Schema` directly */\nexport type HrefSchema<State = never> = {\n\t/** Parse a href string into the state shape */\n\tparse: Schema<State & { href: string }, string>[\"parse\"];\n\t/** Stringify a state shape into a href string */\n\tstringify: Schema<State & { href: string }, string>[\"serialize\"];\n\t/** Compute a new href string based on a given href string and a reducer of the current state. */\n\tparseStringify: Schema<State & { href: string }, string>[\"parserialize\"];\n};\n\n/** @deprecated use `SchemaState` directly */\nexport type HrefSchemaState<T extends HrefSchema> =\n\tT extends HrefSchema<infer U> ? U & { href: string } : never;\n\n/**\n * Helper function to create a `HrefSchema` from a simpler template that only requires the logic for converting between URLs and state objects. The `createSchema` function takes care of implementing the `parse`, `stringify`, and `parseStringify` methods based on the provided template functions.\n *\n * The template requires two functions:\n * - `urlToState`: A function that takes a URL object and returns the corresponding state object.\n * - `stateToUrl`: A function that takes a state object and the current URL, and returns a new URL object that represents the given state.\n *\n * This allows you to focus on the logic for how your application's state maps to the URL structure without having to manually handle the parsing and stringifying of hrefs.\n *\n * @deprecated The `createHrefSchema` function is deprecated in favor of using the more flexible `createStringSchema` function directly with custom parsing and stringifying logic. The `createStringSchema` function can be used to achieve the same functionality without being tied specifically to hrefs, allowing for greater reuse and adaptability in different contexts.\n *\n * @example\n * ```ts\n * import { createHrefSchema } from \"@buildinams/core/schema\";\n *\n * const myHrefSchema = createHrefSchema<{\n *  page: number,\n * }>({\n *   urlToState: (url) => {\n *    return {\n *     page: parseInt(url.searchParams.get(\"page\") || \"1\", 10),\n *    }\n *   },\n *   stateToUrl: (state, url) => {\n *    url.searchParams.delete(\"page\");\n *    if (state.page > 1) {\n *      url.searchParams.set(\"page\", state.page.toString());\n *    }\n *    return url;\n *   }\n * });\n *\n * // Using the schema to parse a href string into state\n * const state = myHrefSchema.parse(\"/products?page=2\");\n * console.log(state); // { page: 2, href: \"/products?page=2\" }\n *\n * // Using the schema to stringify a state object into a href string\n * const href = myHrefSchema.stringify({ page: 3, href: \"/products?page=2\" });\n * console.log(href); // \"/products?page=3\"\n * ```\n */\nexport const createHrefSchema = <T>(\n\ttemplate: HrefSchemaTemplate<T>,\n): HrefSchema<T> =>\n\tcreateStringSchema<T & { href: string }>({\n\t\tstringify: (state) => {\n\t\t\tconst current = hrefToUrl(state.href);\n\t\t\tconst next = template.stateToUrl(state, current);\n\t\t\treturn next.pathname + next.search;\n\t\t},\n\n\t\tparse: (href) => {\n\t\t\tconst current = hrefToUrl(href);\n\t\t\treturn {\n\t\t\t\t...template.urlToState(current),\n\t\t\t\thref: current.pathname + current.search,\n\t\t\t};\n\t\t},\n\t});\n\ntype HrefSchemaTemplate<State = never> = {\n\t/** Parse a href string into the state shape */\n\turlToState: (url: URL) => State;\n\t/** Stringify a state shape and current href into a new href string */\n\tstateToUrl: (state: State, url: URL) => URL;\n};\n"]}

package/dist/schema/index.d.ts

@@ -0,0 +1,58 @@
+import { S as Schema } from '../schema-CfQvhbuU.js';
+export { c as SchemaSerializableState, b as SchemaSerialized, a as SchemaState, d as createSchema } from '../schema-CfQvhbuU.js';
+
+type StringSchema<State = never, SerializableState = State> = {
+    parse: Schema<State, string, SerializableState>["parse"];
+    stringify: Schema<State, string, SerializableState>["serialize"];
+    parseStringify: Schema<State, string, SerializableState>["parserialize"];
+};
+/**
+ * Helper function to create a `StringSchema` which converts between strings and state objects.
+ *
+ * The template requires two functions:
+ * - `parse`: A function that takes a string and returns the corresponding state object.
+ * - `stringify`: A function that takes a state object and returns a string that represents the given state.
+ */
+declare const createStringSchema: <State = never, SerializableState = State>(template: Omit<StringSchema<State, SerializableState>, "parseStringify">) => StringSchema<State, SerializableState>;
+
+/**
+ * Utility schema for parsing and stringifying href strings into structured state objects that include the pathname and URL search parameters.
+ *
+ *  @example
+ * ```ts
+ * import { createSchema, hrefSchema } from "@buildinams/core/schema";
+ *
+ * const myHrefSchema = createSchema<{
+ *  page: number,
+ *  // Used to compute next href - don't use directly. Use `.stringify()` instead
+ *  _href: string
+ * }>({
+ *   parse: (href) => {
+ *    const { searchParams } = hrefSchema.parse(href);
+ *    return {
+ *     page: parseInt(searchParams.get("page") || "1", 10),
+ *     _href: href,
+ *    }
+ *   },
+ *   serialize: (state) => {
+ *    const { pathname, searchParams } = hrefSchema.parse(state._href);
+ *    searchParams.delete("page");
+ *    if (state.page > 1) {
+ *     searchParams.set("page", state.page.toString());
+ *    }
+ *
+ *    // note that `searchParams` are optional for serialization
+ *    return hrefSchema.stringify({ pathname, searchParams });
+ *   }
+ * });
+ * ```
+ */
+declare const hrefSchema: StringSchema<{
+    pathname: string;
+    searchParams: URLSearchParams;
+}, {
+    pathname: string;
+    searchParams?: URLSearchParams;
+}>;
+
+export { Schema, type StringSchema, createStringSchema, hrefSchema };

package/dist/schema/index.js

@@ -0,0 +1,3 @@
+export { createSchema, createStringSchema, hrefSchema } from '../chunk-5KDGGGVO.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/schema-CfQvhbuU.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Defines the schema for parsing and stringifying states to and from primitive values.
+ *
+ * The `Schema` type is a generic type that takes:
+ * - `State`: A state object type.
+ * - `Serialized`: The raw value type
+ * - `SerializableState?`: (optional) A (partial) state object type that can be used for serialization. Defaults to `State` if not provided.
+ *
+ * It returns the following methods:
+ * - `parse`: A function that takes a raw value and returns the corresponding state object.
+ * - `serialize`: A function that takes a (serializable) state object and returns a raw value that represents the given state.
+ * - `parserialize`: A function that takes a raw value and a reducer function - it returns a new raw value that represents the reduced state.
+ *
+ * @see createSchema for a helper function to create a `Schema` from simpler parsing and serializing functions.
+ */
+type Schema<State = any, Serialized = any, SerializableState = State> = {
+    /** Parse a raw value into the state shape */
+    parse: (value: Serialized) => State;
+    /** Serialize a state shape into a raw value */
+    serialize: (state: SerializableState) => Serialized;
+    /** Compute a new serialized value based on a given serialized value and a reducer of the current state. */
+    parserialize: (value: Serialized, next: (state: State) => SerializableState) => Serialized;
+};
+/**
+ * A utility type to extract the state shape from a given `Schema`.
+ */
+type SchemaState<T extends Schema> = T extends Schema<infer U> ? U : never;
+/**
+ * A utility type to extract the serialized value type from a given `Schema`.
+ */
+type SchemaSerialized<T extends Schema> = T extends Schema<any, infer U> ? U : never;
+/**
+ * A utility type to extract the serializable state shape from a given `Schema`.
+ */
+type SchemaSerializableState<T extends Schema> = T extends Schema<any, any, infer U> ? U : never;
+/**
+ * Low-level helper function to create a basic `Schema` that receives the config for converting between serialized values and state objects.
+ *
+ * The template requires two methods:
+ * - `parse`: A method that takes a serialized value and returns the corresponding state object.
+ * - `serialize`: A method that takes a state object and returns a serialized value that represents the given state.
+ *
+ * The `parserialize` method is automatically implemented based on the provided `parse` and `serialize` methods, allowing you to compute a new serialized value based on an existing serialized value and a reducer function for the state.
+ *
+ * @example
+ * ```ts
+ * import { createSchema } from "@buildinams/core/schema";
+ *
+ * const numberSchema = createSchema<
+ *   number, // State
+ *   string // Serialized
+ * >({
+ *   parse: (value) => parseInt(value, 10),
+ *   serialize: (state) => state.toString(),
+ * });
+ *
+ * const result = numberSchema.parserialize("42", (state) => state + 1);
+ * console.log(result); // "43"
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createSchema } from "@buildinams/core/schema";
+ *
+ * const hrefSchema: createSchema<
+ *   { pathname: string, searchParams: URLSearchParams },
+ *   string,
+ *   { pathname: string, searchParams?: URLSearchParams } // SerializableState allows to define different state used for serialization, in this case making searchParams optional to allow for more flexible stringification logic
+ * >({
+ *  parse: (href) => {
+ *    const [pathname = "", search = ""] = href.split("?");
+ *    return {
+ *     pathname,
+ *     searchParams: new URLSearchParams(search),
+ *    };
+ *  },
+ *  serialize: (serializableState) => {
+ *    if (!serializableState.searchParams) return serializableState.pathname;
+ *    const paramsString = serializableState.searchParams.toString();
+ *    return serializableState.pathname + (paramsString ? `?${paramsString}` : "");
+ *  },
+ * })
+ * ```
+ */
+declare const createSchema: <State = never, Serialized = never, SerializableState = State>(template: Omit<Schema<State, Serialized, SerializableState>, "parserialize">) => Schema<State, Serialized, SerializableState>;
+
+export { type Schema as S, type SchemaState as a, type SchemaSerialized as b, type SchemaSerializableState as c, createSchema as d };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@buildinams/core",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"type": "module",
 	"author": "Build in Amsterdam <development@buildinamsterdam.com> (https://www.buildinamsterdam.com/)",
 	"repository": {
@@ -29,6 +29,10 @@
 			"types": "./dist/navigation/index.d.ts",
 			"default": "./dist/navigation/index.js"
 		},
+		"./schema": {
+			"types": "./dist/schema/index.d.ts",
+			"default": "./dist/schema/index.js"
+		},
 		"./store": {
 			"types": "./dist/store/index.d.ts",
 			"default": "./dist/store/index.js"
@@ -42,6 +46,9 @@
 			"./navigation": [
 				"./dist/navigation/index.d.ts"
 			],
+			"./schema": [
+				"./dist/schema/index.d.ts"
+			],
 			"./store": [
 				"./dist/store/index.d.ts"
 			]
@@ -52,7 +59,7 @@
 		"README.md"
 	],
 	"publishConfig": {
-		"registry": "https://npm.pkg.github.com",
+		"registry": "https://registry.npmjs.org",
 		"access": "public"
 	},
 	"devDependencies": {