Merge pull request #63 from marshallswain/feat/allowUnnamedQueryForEx…

…ternal

feat: allowUnnamedQueryForExternal for service/app & docs - migrate to vitepress

.gitignore

@@ -118,4 +118,5 @@ data/
 
 # vuepress
 
-docs/.vuepress/dist
+docs/.vitepress/dist
+docs/.vitepress/cache

README.md

@@ -80,7 +80,7 @@ Each populate object must/can have the following properties:
 | `keyHere`  | The primary or secondary key for the current entry<br><br>**required**<br>**Type:** `{String}` |
 | `keyThere` | The primary or secondary key for the referenced entry/entries<br><br>**required**<br>**Type:** `{String}` |
 | `asArray`  | Is the referenced item a single entry or an array of entries?<br><br>**optional - default:** `true`<br>**Type:** `{Boolean}`
-| `params`   | Additional params to be passed to the underlying service.<br>You can mutate the passed `params` object or return a newly created `params` object which gets merged deeply <br>Merged deeply after the params are generated internally.<br><quote>**ProTip:** You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss</quote><br><br>**optional - default:** `{}`<br>**Type:** `{Object | Function(params, context): undefined|params}` |
+| `params`   | Additional params to be passed to the underlying service.<br>You can mutate the passed `params` object or return a newly created `params` object which gets merged deeply <br>Merged deeply after the params are generated internally.<br>**ProTip:** You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss<br><br>**optional - default:** `{}`<br>**Type:** `{Object | Function(params, context): undefined|params}` |
 
 ### Create named queries to use from connected clients.
 

docs/.vitepress/config.mts

@@ -0,0 +1,59 @@
+import { defineConfig } from 'vitepress'
+import { name, description, defaultBranch, repository } from './meta'
+import { version } from '../../package.json'
+
+export default defineConfig({
+  title: name,
+  lastUpdated: true,
+  description,
+  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
+  themeConfig: {
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: 'Hooks', link: '/hooks' },
+        ],
+      },
+    ],
+    nav: [
+      {
+        text: `v${version}`,
+        items: [
+          {
+            text: 'Changelog',
+            link: `https://github.com/${repository}/blob/${defaultBranch}/CHANGELOG.md`,
+          },
+          {
+            text: 'Contributing',
+            link: `https://github.com/${repository}/blob/${defaultBranch}/.github/contributing.md`,
+          },
+        ],
+      },
+    ],
+    editLink: {
+      pattern: `https://github.com/${repository}/edit/${defaultBranch}/docs/:path`,
+    },
+    socialLinks: [
+      {
+        icon: 'twitter',
+        link: 'https://twitter.com/feathersjs',
+      },
+      {
+        icon: 'discord',
+        link: 'https://discord.gg/qa8kez8QBx',
+      },
+      {
+        icon: 'github',
+        link: `https://github.com/${repository}`,
+      },
+    ],
+    logo: '/img/graph-populate-logo.png',
+    lastUpdatedText: 'Last Updated',
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'MIT Licensed | © 2019-present Marshall Thompson',
+    },
+  },
+})

docs/.vitepress/meta.ts

@@ -0,0 +1,4 @@
+export const name = "feathers-graph-populate";
+export const description = "Add lightning fast, GraphQL-like populates to your FeathersJS API.";
+export const repository = "marshallswain/feathers-graph-populate" as const;
+export const defaultBranch = "master" as const;

docs/.vitepress/style/main.css

@@ -0,0 +1,11 @@
+/**
+ * Colors
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-brand: #cc0099;
+  --vp-c-brand-light: #d600a0;
+  --vp-c-brand-lighter: #e600ac;
+  --vp-c-brand-dark: #cc0099;
+  --vp-c-brand-darker: rgb(118, 2, 120);
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,6 @@
+import Theme from 'vitepress/theme'
+import '../style/main.css'
+
+export default {
+  ...Theme,
+}

docs/getting-started.md

@@ -1,7 +1,4 @@
----
-title: Getting Started
-sidebarDepth: 3
----
+# Getting Started
 
 <!--- Usage ------------------------------------------------------------------------------------ -->
 [![Github Actions](https://github.com/marshallswain/feathers-graph-populate/actions/workflows/node.js.yml/badge.svg)](https://github.com/marshallswain/feathers-graph-populate/actions)
@@ -39,7 +36,9 @@ Configuring `feathers-graph-populate` in the `app.js` file, allows the global us
 ```js
 // src/app.js
 const graphPopulate = require('feathers-graph-populate')
-app.configure(graphPopulate())
+app.configure(graphPopulate({
+  allowUnnamedQueryForExternal: false // default: false
+}))
 ```
 
 ### Define the Relationships
@@ -108,7 +107,7 @@ Each populate object must/can have the following properties:
 | `asArray`        | Is the referenced item a single entry or an array of entries?<br><br>**optional - default:** `true`<br>**Type:** `Boolean`
 | `requestPerItem` | Decided wether your `params` object/function runs against each item individually or bundled. Most of the time you don't need this.<br><br>**optional - default:<br>- `false`** (if `keyHere` and `keyThere` are defined)<br>- **`true`** (if `keyHere` and `keyThere` are not defined)<br>**Type:** `String`
 | `catchOnError`   | Wether the hook continues populating, if an error occurs (e.g. because of missing authentication) or throws. Also can be set on the prior options<br><br>**optional - default:** `false`<br>**Type:**: `Boolean` |
-| `params`         | Additional params to be passed to the underlying service.<br>You can mutate the passed `params` object or return a newly created `params` object which gets merged deeply <br>Merged deeply after the params are generated internally.<br><quote>**ProTip #1:** You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss</quote><br><quote>**ProTip #2:** If you don't define `keyHere` and `keyThere` or set `requestPerItem` to `true` the function has access to the _`this` keyword_ being the individual item the request will be made for.</quote><br><quote>**ProTip #3**: You can skip a `requestPerItem` if it returns `undefined`.</quote><br><quote>**ProTip #4**: The hook whats for async functions!</quote><br><br>**optional - default:** `{}`<br>**Possible types:**<br>- `Object`: _will be merged with params - simple requests_<br>- `Function(params, context, { path, service }) => params`: _needs to return the `params` or a new one which gets merged deeply - more complex_<br>- `Function(params, context, { path, service }) => Promise<params>`<br>- `[Object | Function]` |
+| `params`         | Additional params to be passed to the underlying service.<br>You can mutate the passed `params` object or return a newly created `params` object which gets merged deeply <br>Merged deeply after the params are generated internally.<br>**ProTip #1:** You can use this for adding a '$select' property or passing authentication and user data from 'context' to 'params' to restrict accesss<br>**ProTip #2:** If you don't define `keyHere` and `keyThere` or set `requestPerItem` to `true` the function has access to the _`this` keyword_ being the individual item the request will be made for.<br>**ProTip #3**: You can skip a `requestPerItem` if it returns `undefined`.<br>**ProTip #4**: The hook whats for async functions!<br><br>**optional - default:** `{}`<br>**Possible types:**<br>- `Object`: _will be merged with params - simple requests_<br>- `Function(params, context, { path, service }) => params`: _needs to return the `params` or a new one which gets merged deeply - more complex_<br>- `Function(params, context, { path, service }) => Promise<params>`<br>- `[Object | Function]` |
 
 ### Create Named Queries
 
@@ -209,9 +208,9 @@ feathersClient.service('users').find({
 
 > Notice that the `$populateParams` is a custom `param`, so it is outside of the `query` object.
 
-### Unnamed Queries (internal only)
+### Unnamed Queries (for internal requests only by default or with option: 'allowUnnamedQueryForExternal' for external requests)
 
-For internal requests, in addition to supporting named queries, you can directly provide a query object. This allows custom, unnamed queries like the following:
+In addition to supporting named queries, you can directly provide a query object. This allows custom, unnamed queries like the following:
 
 ```js
 app.service('users').find({

docs/graph-populate-hooks.md → docs/hooks.md

@@ -1,7 +1,4 @@
----
-title: graph-populate hooks
-sidebarDepth: 3
----
+# Hooks
 
 ## Introduction
 

docs/index.md

@@ -1,16 +1,24 @@
 ---
-home: true
-heroImage: /img/graph-populate-logo.png
-heroText: feathers-graph-populate
-tagLine: Add lightning fast, GraphQL-like populates to your FeathersJS API.
-actionText: Get Started
-actionLink: ./getting-started.md
+layout: home
+
+hero: 
+  name: feathers-graph-populate
+  image:
+    src: /img/graph-populate-logo.png
+    alt: feathers-graph-populate
+  tagline: Add lightning fast, GraphQL-like populates to your FeathersJS API.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: ./getting-started.md
+
 features:
-- title: Super Duper, Hyper Mega Fast 🚀
-  details: API designed for rocket speed without the rocket science.
-- title: Become a Relationship Expert 💝
-  details: Defining a relationship is as simple as specifying the primary and foreign keys.
-- title: Dive Way Down with Deep Populates 🏊‍♂️
-  details: Simple query syntax supports multiple, nested, and even recursive populates.
-footer: MIT Licensed | Copyright © 2019-present Marshall Thompson
+  - title: Super Duper, Hyper Mega Fast 🚀
+    details: API designed for rocket speed without the rocket science.
+  - title: Become a Relationship Expert 💝
+    details: Defining a relationship is as simple as specifying the primary and foreign keys.
+  - title: Dive Way Down with Deep Populates
+    detaules: Simple query syntax supports multiple, nested and even recursive populates.
+
+footer: MIT Licensed | © 2019-present Marshall Thompson
 ---