feat: add document (#123)

* docs: add document

* misc: format codes

* misc: add action to publish document

* fix: tscheck

* fix: type errors

* fix: actions

.github/actions/init-node/action.yml

@@ -9,7 +9,7 @@ runs:
     - uses: actions/setup-node@v4
       with:
         cache: yarn
-        node-version: 18
+        node-version: 20
 
     - name: cache node_modules
       id: cache_node_modules

.github/workflows/document.yml

@@ -0,0 +1,36 @@
+---
+name: Deploy Document to GitHub Pages
+
+on:
+  push:
+    tags:
+      - "**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install, build, and upload your site
+        uses: withastro/action@v1
+        with:
+          path: ./docs
+          node-version: 20
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/release.yml

@@ -34,4 +34,4 @@ jobs:
         publish: yarn run changeset publish
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        NPM_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -66,3 +66,14 @@ jobs:
 
       - run: yarn test:type
 
+  astro-check:
+    name: "Test: astro-check"
+    runs-on: ubuntu-latest
+    needs:
+      - init__node
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/init-node
+
+      - run: yarn test:doc
+

biome.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://biomejs.dev/schemas/1.4.1/schema.json",
   "files": {
-    "ignore": ["node_modules", "coverage"]
+    "ignore": ["node_modules", "coverage", ".astro", ".yarn"]
   },
   "organizeImports": {
     "enabled": true

docs/.gitignore

@@ -0,0 +1 @@
+.astro

docs/astro.config.ts

@@ -0,0 +1,35 @@
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+
+// biome-ignore lint/style/noDefaultExport: <explanation>
+export default defineConfig({
+  site: 'https://hacomono-lib.github.io',
+  base: '/json-origami',
+  integrations: [
+    starlight({
+      title: 'json-origami',
+      social: {
+        github: 'https://github.com/hacomono-lib/json-origami',
+      },
+      sidebar: [
+        {
+          label: 'Home',
+          link: '/',
+        },
+        {
+          label: 'Introduction',
+          collapsed: false,
+          items: [
+            { label: 'Getting Started', link: '/guides/start' },
+            { label: 'Concepts', link: '/guides/concepts' },
+          ],
+        },
+        {
+          label: 'Api',
+          collapsed: false,
+          autogenerate: { directory: '/api', collapsed: false },
+        },
+      ],
+    }),
+  ],
+})

docs/src/content/config.ts

@@ -0,0 +1,7 @@
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
+import { defineCollection } from 'astro:content'
+
+export const collections: Record<string, ReturnType<typeof defineCollection>> = {
+  docs: defineCollection({ schema: docsSchema() }),
+  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+}

docs/src/content/docs/api/fold.md

@@ -0,0 +1,76 @@
+---
+title: fold
+description: fold function converts a JSON object into key-value pair object by folding it.
+---
+
+`fold` function converts a JSON object into key-value pair object by folding it.
+
+```ts
+fold(object, option?)
+```
+
+## Arguments
+
+- ### `object`
+
+  type: `object`
+
+  The JSON object to fold.
+
+  e.g.
+  `{ a: { b: "c" } }` will be folded to `{ "a.b": "c" }`.
+
+- ### `option`
+
+  type: `object`
+
+  - #### `arrayIndex`
+
+    type: `"dot" | "bracket"`
+
+    default: `"bracket"`
+
+    The index of array to fold.
+
+    e.g.
+    `{ a: ["b"] }` will be folded to `{ "a[0]": "b" }` if `arrayIndex` is `"bracket"`,
+    and will be folded to `{ "a.0": "b" }` if `arrayIndex` is `"dot"`.
+
+  - #### `keyPrefix`
+
+    type: `string`
+
+    default: `""`
+
+    The prefix to prepend to the folded key.
+
+### Example
+
+```ts
+import { fold } from 'json-origami';
+
+const user = {
+  id: 1,
+  name: 'John',
+  age: 20,
+  address: {
+    street: '123 Main St',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+  },
+};
+
+const folded = fold(user)
+/**
+ * {
+ *   id: 1,
+ *   name: 'John',
+ *   age: 20,
+ *   'address.street': '123 Main St',
+ *   'address.city': 'New York',
+ *   'address.state': 'NY',
+ *  'address.zip': '10001',
+ * }
+ */
+```

docs/src/content/docs/api/omit.md

@@ -0,0 +1,69 @@
+---
+title: omit
+description: omit function omits the specified keys from a JSON object.
+---
+
+`omit` function omits the specified keys from a JSON object.
+
+```ts
+omit(object, keys, option?)
+```
+
+## Arguments
+
+- ### `object`
+
+  type: `object`
+
+  The JSON object to omit keys from.
+
+- ### `keys`
+
+  type: `string[]`
+
+  The keys to omit.
+
+- ### `option`
+
+  type: `object`
+
+  - #### `arrayIndex`
+
+    type: `"dot" | "bracket"`
+
+    default: `"bracket"`
+
+    The index of array to omit.
+
+    e.g.
+    `[ "a[0]" ]` will omit to `{ a: ["b"] }` if `arrayIndex` is `"bracket"`,
+    and `[ "a.0" ]` will omit to `{ a: { 0: "b" } }` if `arrayIndex` is `"dot"`.
+
+### Example
+
+```ts
+import { omit } from 'json-origami';
+
+const user = {
+  id: 1,
+  name: 'John',
+  age: 20,
+  address: {
+    street: '123 Main St',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+  },
+};
+
+const omitted = omit(user, ['id', 'name', 'address.street', 'address.city']);
+/**
+ * {
+ *   age: 20,
+ *   address: {
+ *     state: 'NY',
+ *     zip: '10001',
+ *   },
+ * }
+ */
+```

docs/src/content/docs/api/pick.md

@@ -0,0 +1,71 @@
+---
+title: pick
+description: pick function picks the specified keys from a JSON object.
+---
+
+`pick` function picks the specified keys from a JSON object.
+
+```ts
+pick(object, keys, option?)
+```
+
+## Arguments
+
+- ### `object`
+
+  type: `object`
+
+  The JSON object to pick keys from.
+
+- ### `keys`
+
+  type: `string[]`
+
+  The keys to pick.
+
+- ### `option`
+
+  type: `object`
+
+  - #### `arrayIndex`
+
+    type: `"dot" | "bracket"`
+
+    default: `"bracket"`
+
+    The index of array to pick.
+
+    e.g.
+    `[ "a[0]" ]` will pick to `{ a: ["b"] }` if `arrayIndex` is `"bracket"`,
+    and `[ "a.0" ]` will pick to `{ a: { 0: "b" } }` if `arrayIndex` is `"dot"`.
+
+### Example
+
+```ts
+import { pick } from 'json-origami';
+
+const user = {
+  id: 1,
+  name: 'John',
+  age: 20,
+  address: {
+    street: '123 Main St',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+  },
+};
+
+const picked = pick(user, ['id', 'name', 'address.street', 'address.city']);
+
+/**
+ * {
+ *   id: 1,
+ *   name: 'John',
+ *   address: {
+ *     street: '123 Main St',
+ *     city: 'New York',
+ *   },
+ * }
+ */
+```