132 |
133 | return JSON.parse(JSON.stringify(evalQuery))
134 | }
135 |
136 | export default FilterInput
137 |
--------------------------------------------------------------------------------
/admin/src/components/flow-handle.tsx:
--------------------------------------------------------------------------------
1 | import { Handle, HandleProps, Position } from 'reactflow'
2 | import clsx from 'clsx'
3 |
4 | interface Props extends HandleProps {
5 | className?: string
6 | }
7 |
8 | function FlowHandle({ className, ...props }: Props) {
9 | return (
10 |
21 |
22 |
23 | )
24 | }
25 |
26 | export default FlowHandle
27 |
--------------------------------------------------------------------------------
/admin/src/components/general-error.tsx:
--------------------------------------------------------------------------------
1 | import AppError from '@/lib/app-error'
2 | import { Link } from 'react-router-dom'
3 | import { useRouteError } from 'react-router-dom'
4 |
5 | interface Props {
6 | error: AppError
7 | }
8 |
9 | function GeneralErrorBoundary({ error }: Props) {
10 | console.error(error)
11 |
12 | return (
13 |
14 |
15 | {error.data?.status ? (
16 |
17 | ) : (
18 |
19 | )}
20 |
21 |
22 |
23 |
31 |
32 | release_alert
33 |
34 |
35 | An API error occurred
36 |
37 | Status code: {error.data.status}
38 |
39 |
40 | {error.data.detail && (
41 | <>
42 |
43 | {error.data.detail}
44 |
45 |
46 | )}
47 |
48 | {error.data.status === 401 && (
49 |
50 |
51 | You may need to login again. If you think this is a mistake, check{' '}
52 |
56 | our issues
57 | {' '}
58 | or raise one.{' '}
59 |
60 |
61 |
62 |
68 | Login
69 |
70 |
71 |
76 |
The resource you are looking for does not exist.
77 |
82 | This error is unexpected. Check the console logs to get an idea of
83 | what could be happening.
84 |
85 | )}
86 |
87 | )
88 | }
89 |
90 | function UnknownErrorContent() {
91 | const error = useRouteError() as Error
92 |
93 | return (
94 | <>
95 |
96 |
97 | release_alert
98 |
99 |
100 | An error occurred
101 |
102 | The app encountered an error it could not handle
103 |
104 |
105 | Message
106 | {error.message}
107 |
108 | Stacktrace
109 |
110 | Check stacktrace from the browser's developer Console. If you think this
111 | is unexpected, please check{' '}
112 |
118 | our issues
119 | {' '}
120 | or raise one.
121 |
Loading hook…
36 | }
37 |
38 | return (
39 |
45 |
46 |
51 |
52 |
61 |
62 |
67 |
68 | {hookInfo.configSchema && (
69 |
74 | )}
75 |
38 |
setSearchKey((e.target as HTMLInputElement).value)}
41 | placeholder="Search and add hook"
42 | type="search"
43 | value={searchKey}
44 | onFocus={() => setFocused(true)}
45 | onBlur={() => setFocused(false)}
46 | />
47 |
48 | {showResults && (
49 |
67 | )}
68 |
43 | {link.leading}
44 |
45 |
46 | {link.title}
47 |
48 |
49 |
50 | {hasChildren && (
51 |
52 | {expanded ? 'expand_less' : 'expand_more'}
53 |
54 | )}
55 |
56 | )
57 | }
58 |
59 | function LinkItem({
60 | link,
61 | children,
62 | }: {
63 | link: LinkProp
64 | children?: LinkProp[]
65 | }) {
66 | const [expanded, setExpanded] = React.useState(false)
67 |
68 | return (
69 |
70 |
setExpanded((v) => !v)}
73 | hasChildren={Boolean(children?.length)}
74 | expanded={expanded}
75 | />
76 |
77 | {children && expanded && (
78 |
79 | {children.map((link) => (
80 | -
81 |
82 |
83 | ))}
84 |
85 | )}
86 |
93 | {links.map((link) => (
94 | -
95 |
96 |
97 | ))}
98 |
99 | )
100 | }
101 |
102 | export default NavLinks
103 |
--------------------------------------------------------------------------------
/admin/src/components/popover.tsx:
--------------------------------------------------------------------------------
1 | import * as RadixPopover from '@radix-ui/react-popover'
2 | import React from 'preact/compat'
3 |
4 | interface Props extends React.PropsWithChildren {
5 | trigger: React.ReactNode
6 | }
7 |
8 | function Popover({ children, trigger }: Props) {
9 | return (
10 |
11 | {trigger}
12 |
13 | {children}
14 |
15 |
16 | )
17 | }
18 |
19 | export { Popover }
20 |
--------------------------------------------------------------------------------
/admin/src/components/schema-fields.tsx:
--------------------------------------------------------------------------------
1 | import {
2 | Control,
3 | Controller,
4 | FieldValues,
5 | UseFormRegister,
6 | } from 'react-hook-form'
7 | import CodeEditor from './code-editor'
8 | import Input from './input'
9 | import type { SchemaDefinitions } from 'mangobase'
10 | import clsx from 'clsx'
11 |
12 | interface Props {
13 | schema: SchemaDefinitions
14 | register: UseFormRegister
15 | control: Control
16 | }
17 |
18 | const EDITOR_OPTIONS = {
19 | acceptSuggestionOnEnter: 'off',
20 | codeLens: false,
21 | contextmenu: false,
22 | foldingHighlight: false,
23 | fontFamily: 'IBM Plex Mono, Zed Mono, monospace',
24 | fontLigatures: true,
25 | fontSize: 14,
26 | hover: {
27 | enabled: false,
28 | },
29 | lineDecorationsWidth: 0,
30 | lineNumbersMinChars: 2,
31 | minimap: { enabled: false },
32 | overviewRulerBorder: false,
33 | overviewRulerLanes: 0,
34 | parameterHints: {
35 | enabled: false,
36 | },
37 | quickSuggestions: {
38 | comments: false,
39 | other: false,
40 | strings: false,
41 | },
42 | renderLineHighlight: 'none',
43 | scrollbar: {
44 | horizontalSliderSize: 5,
45 | verticalSliderSize: 5,
46 | },
47 | suggestOnTriggerCharacters: false,
48 | tabCompletion: 'off',
49 | wordBasedSuggestions: false,
50 | } as const
51 |
52 | function SchemaFields({ control, register, schema }: Props) {
53 | return (
54 |
138 | )
139 | }
140 |
141 | export default SchemaFields
142 |
--------------------------------------------------------------------------------
/admin/src/components/select.tsx:
--------------------------------------------------------------------------------
1 | import React from 'preact/compat'
2 | import clsx from 'clsx'
3 |
4 | type Props = React.ComponentProps<'select'>
5 |
6 | const Select = React.forwardRef(
7 | (
8 | { className, ...props }: Props,
9 | ref: React.ForwardedRef
10 | ) => {
11 | return (
12 |
20 | )
21 | }
22 | )
23 |
24 | export default Select
25 |
--------------------------------------------------------------------------------
/admin/src/components/service-node.tsx:
--------------------------------------------------------------------------------
1 | import { Connection, Position } from 'reactflow'
2 | import FlowHandle from './flow-handle'
3 | import { METHODS } from '../client/collection'
4 |
5 | function ServiceNode() {
6 | function checkSourceConnection(connection: Connection) {
7 | return connection.source !== 'service'
8 | }
9 |
10 | function checkTargetConnection(connection: Connection) {
11 | return connection.target !== 'service'
12 | }
13 |
14 | return (
15 |
16 |
17 |
18 | sync_alt
19 |
20 |
21 |
22 |
Service node
23 |
Methods
24 |
26 |
27 |
28 | {METHODS.map((method) => (
29 | -
30 |
36 |
37 |
{method}
38 |
39 |
45 |
46 | ))}
47 |
48 |
13 |
14 | {snacks.value.map((snack) => {
15 | if (snack.type === 'custom') return snack.content
16 |
17 | return (
18 | -
19 |
29 |
30 |
31 | {ICONS[snack.type]}
32 |
33 |
{snack.content}
34 |
35 |
36 |
41 |
42 |
44 | )
45 | })}
46 |
47 |
21 | {ellipsize(JSON.stringify(value), 48)}
22 |
23 | )
24 |
25 | case 'boolean':
26 | return (
27 |
28 | {JSON.stringify(value)}
29 |
30 | )
31 |
32 | default: {
33 | if (typeof value === 'string') {
34 | return {ellipsize(value, 48)}
35 | }
36 |
37 | return (
38 |
39 | {ellipsize(JSON.stringify(value), 48)}
40 |
41 | )
42 | }
43 | }
44 | }
45 |
46 | function ellipsize(text: string | undefined, length: number) {
47 | if (!text) {
48 | return null
49 | }
50 |
51 | if (text.length <= length) {
52 | return text
53 | }
54 |
55 | return `${text.slice(0, length)}…`
56 | }
57 |
58 | export default Value
59 |
--------------------------------------------------------------------------------
/admin/src/data/app-developers.ts:
--------------------------------------------------------------------------------
1 | import app from '../mangobase-app'
2 | import { signal } from '@preact/signals'
3 |
4 | interface User {
5 | _id: string
6 | fullname: string
7 | username: string
8 | }
9 |
10 | const appDevelopers = signal([])
11 |
12 | async function loadAppDevelopers() {
13 | const users = await app.collection('users')
14 | const { data } = await users.find({ role: 'dev' })
15 |
16 | appDevelopers.value = data
17 | }
18 |
19 | export default appDevelopers
20 | export { loadAppDevelopers }
21 |
--------------------------------------------------------------------------------
/admin/src/data/collections.ts:
--------------------------------------------------------------------------------
1 | import Collection from '../client/collection'
2 | import app from '../mangobase-app'
3 | import { signal } from '@preact/signals'
4 |
5 | const collections = signal([])
6 |
7 | async function loadCollections() {
8 | const cols = await app.collections()
9 | collections.value = cols
10 | }
11 |
12 | export default collections
13 | export { loadCollections }
14 |
--------------------------------------------------------------------------------
/admin/src/data/hooks-registry.ts:
--------------------------------------------------------------------------------
1 | import type { Definition } from 'mangobase'
2 | import app from '../mangobase-app'
3 | import { signal } from '@preact/signals'
4 |
5 | interface Hook {
6 | configSchema: Record
7 | description: string
8 | id: string
9 | name: string
10 | }
11 |
12 | const hooksRegistry = signal([])
13 |
14 | async function loadHooksRegistry() {
15 | hooksRegistry.value = ((await app.hookRegistry()) as Hook[]).sort((a, b) =>
16 | a.name.localeCompare(b.name)
17 | )
18 | }
19 |
20 | export default hooksRegistry
21 | export { loadHooksRegistry }
22 | export type { Hook }
23 |
--------------------------------------------------------------------------------
/admin/src/data/logs.ts:
--------------------------------------------------------------------------------
1 | import app from '../mangobase-app'
2 | import dayjs from 'dayjs'
3 | import { signal } from '@preact/signals'
4 |
5 | interface Log {
6 | _id: string
7 | category: string
8 | created_at: string
9 | data: any
10 | label: string
11 | status: number
12 | time: number
13 | }
14 |
15 | interface LogStat {
16 | _id: string
17 | date: string
18 | requests: number
19 | }
20 |
21 | const logs = signal([])
22 | const logStats = signal([])
23 |
24 | async function loadLogs() {
25 | const { data } = await app.req.get('_dev/logs?$sort[created_at]=-1')
26 | logs.value = data.data
27 | }
28 |
29 | function fillMissingHours(logs: LogStat[]) {
30 | const maxDaysAgo = Date.now() - 2 * 24 * 60 * 60 * 1000 // 48 hours ago
31 |
32 | const now = Date.now()
33 | const res: LogStat[] = []
34 | let logsCursor = 0
35 |
36 | let currentTime = maxDaysAgo
37 |
38 | while (currentTime <= now) {
39 | const log = logs[logsCursor]
40 |
41 | if (dayjs(log.date).isSame(currentTime, 'hour')) {
42 | logsCursor++
43 | res.push(log)
44 | } else {
45 | const date = dayjs(currentTime).format('YYYY-MM-DDTHH:00:00')
46 | res.push({ _id: date, date, requests: 0 })
47 | }
48 |
49 | currentTime += 60 * 60 * 1000 // add an hour
50 | }
51 |
52 | return res
53 | }
54 |
55 | async function loadLogStats() {
56 | const { data } = await app.req.get('_dev/log-stats')
57 | logStats.value = fillMissingHours(data)
58 | }
59 |
60 | export default logs
61 | export { loadLogs, logStats, loadLogStats }
62 | export type { Log }
63 |
--------------------------------------------------------------------------------
/admin/src/data/schema-refs.ts:
--------------------------------------------------------------------------------
1 | import { Ref } from 'mangobase'
2 | import app from '../mangobase-app'
3 | import { signal } from '@preact/signals'
4 |
5 | const schemaRefs = signal([])
6 |
7 | async function loadSchemaRefs() {
8 | schemaRefs.value = (await app.req.get('_dev/schema-refs')).data
9 | schemaRefs.value.sort((a, b) => a.name.localeCompare(b.name))
10 | }
11 |
12 | export default schemaRefs
13 | export { loadSchemaRefs }
14 |
--------------------------------------------------------------------------------
/admin/src/extras.css:
--------------------------------------------------------------------------------
1 | .text-secondary {
2 | @apply text-zinc-500 dark:text-neutral-400;
3 | }
4 |
5 | th {
6 | text-align: start;
7 | color: var(--secondary-color);
8 | padding: 0.5rem;
9 | margin-bottom: 0.5rem;
10 | }
11 |
12 | td {
13 | padding-left: 0.5rem;
14 | padding-right: 0.5rem;
15 | }
16 |
17 | fieldset {
18 | border: 0;
19 | padding: 0;
20 | }
21 |
22 | ::-webkit-scrollbar {
23 | width: 5px;
24 | height: 5px;
25 | }
26 |
27 | ::-webkit-scrollbar-thumb {
28 | background: #bfc3c6;
29 | border-radius: 0.25rem;
30 | }
31 |
32 | @media (prefers-color-scheme: dark) {
33 | ::-webkit-scrollbar-thumb {
34 | background-color: #5e6062;
35 | }
36 | }
37 |
38 | ::-webkit-scrollbar-track {
39 | background: transparent;
40 | }
41 |
--------------------------------------------------------------------------------
/admin/src/index.css:
--------------------------------------------------------------------------------
1 | @import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;700&display=swap");
2 |
3 | @tailwind base;
4 | @tailwind components;
5 | @tailwind utilities;
6 |
7 | @font-face {
8 | font-family: "Zed Mono";
9 | src: url("/zed-mono/zed-mono-regular.woff2");
10 | font-weight: 400;
11 | }
12 |
13 | @font-face {
14 | font-family: "Zed Mono";
15 | src: url("/zed-mono/zed-mono-medium.woff2");
16 | font-weight: 500;
17 | }
18 |
19 | @font-face {
20 | font-family: "Zed Mono";
21 | src: url("/zed-mono/zed-mono-bold.woff2");
22 | font-weight: 700;
23 | }
24 |
25 | @font-face {
26 | font-family: "Zed Mono";
27 | src: url("/zed-mono/zed-mono-italic.woff2");
28 | font-style: italic;
29 | }
30 |
31 | .material-symbols-rounded {
32 | font-display: block;
33 | }
34 |
35 | :root {
36 | color-scheme: light dark;
37 | accent-color: #0E9544;
38 |
39 | font-size: 14px;
40 | font-family: "Zed Mono", sans-serif;
41 | }
42 |
43 | input[type="checkbox"] {
44 | @apply rounded-md bg-zinc-200 dark:bg-neutral-700 w-5 h-4 focus:ring-zinc-100 dark:focus:ring-neutral-500 focus:ring-1 focus:ring-offset-0;
45 | }
46 |
47 | .react-flow__controls-button {
48 | @apply dark:!bg-neutral-600 dark:!border-b-neutral-700 dark:!text-white dark:hover:!bg-neutral-500;
49 | }
50 |
51 | .react-flow__controls-button svg path {
52 | fill: currentColor;
53 | }
54 |
55 | .react-flow__attribution {
56 | @apply dark:!bg-neutral-700 rounded rounded-b-none;
57 | }
58 |
59 | code {
60 | @apply bg-zinc-200 dark:bg-neutral-600 text-zinc-600 dark:text-neutral-200 font-['IBM_Plex_Mono'] rounded px-1;
61 | }
62 |
63 | label {
64 | display: block
65 | }
66 |
67 | .material-symbols-rounded {
68 | @apply inline-flex items-center align-middle;
69 | }
70 |
71 | .cm-editor.cm-focused {
72 | @apply outline-none;
73 | }
74 |
75 | .cm-line {
76 | @apply font-['IBM_Plex_Mono'];
77 | }
78 |
--------------------------------------------------------------------------------
/admin/src/layouts/AdminLayout.tsx:
--------------------------------------------------------------------------------
1 | import { NavLink, Outlet, useNavigate } from 'react-router-dom'
2 | import AVATAR_COLORS from '@/lib/avatar-colors'
3 | import Avatar from 'boring-avatars'
4 | import React from 'preact/compat'
5 | import app from '../mangobase-app'
6 | import clsx from 'clsx'
7 |
8 | const navLinks = [
9 | {
10 | href: '/collections',
11 | icon: toolbar,
12 | title: 'Collections',
13 | },
14 | {
15 | href: '/logs',
16 | icon: bug_report,
17 | title: 'Logs',
18 | },
19 | {
20 | href: '/settings',
21 | icon: page_info,
22 | title: 'Settings',
23 | },
24 | {
25 | href: 'https://degreat.co.uk/mangobase/guide',
26 | icon: article,
27 | title: 'Docs',
28 | },
29 | ]
30 |
31 | function AdminLayout() {
32 | const navigate = useNavigate()
33 | const auth = app.get('auth')
34 |
35 | React.useEffect(() => {
36 | !auth && navigate('/login')
37 | }, [auth, navigate])
38 |
39 | if (!auth) {
40 | return null
41 | }
42 |
43 | const { user } = auth
44 |
45 | return (
46 |
47 |
79 |
80 |
81 |
82 |
83 |
10 |
11 |
12 |
13 | {children}
14 |
15 |
[ {
8 | if (!schemaRefs.value?.length) {
9 | await loadCollections()
10 | await loadSchemaRefs()
11 | }
12 |
13 | if (name === 'new') {
14 | return {
15 | name: 'Add new schema',
16 | schema: {},
17 | }
18 | }
19 |
20 | const nameParts = name.split('/')
21 | const refName = nameParts.pop()!
22 | const [scope] = nameParts
23 |
24 | try {
25 | const { data: schema } = await app.req.get(
26 | `_dev/schema-refs/${refName}?$scope=${scope || ''}`
27 | )
28 |
29 | return schema
30 | } catch (err) {
31 | throw new AppError((err as any).message, err)
32 | }
33 | }
34 |
--------------------------------------------------------------------------------
/admin/src/lib/indexed.ts:
--------------------------------------------------------------------------------
1 | function* indexed(array: Array) {
2 | let i = 0
3 | while (i < array.length) {
4 | yield [array[i], i] as const
5 | i++
6 | }
7 | }
8 |
9 | export default indexed
10 |
--------------------------------------------------------------------------------
/admin/src/lib/node-types.ts:
--------------------------------------------------------------------------------
1 | import HookNode, { HOOK_NODE_TYPE } from '@/components/hook-node'
2 | import ServiceNode, { SERVICE_NODE_TYPE } from '@/components/service-node'
3 |
4 | const nodeTypes = {
5 | [HOOK_NODE_TYPE]: HookNode,
6 | [SERVICE_NODE_TYPE]: ServiceNode,
7 | }
8 |
9 | export default nodeTypes
10 |
--------------------------------------------------------------------------------
/admin/src/lib/random-str.ts:
--------------------------------------------------------------------------------
1 | const candidates =
2 | 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'
3 |
4 | function randomStr(length = 8) {
5 | return Array.from({ length })
6 | .map(() => candidates[Math.floor(Math.random() * candidates.length)])
7 | .join('')
8 | }
9 |
10 | export default randomStr
11 |
--------------------------------------------------------------------------------
/admin/src/lib/remove-fields-item.ts:
--------------------------------------------------------------------------------
1 | import {
2 | FieldValues,
3 | UseFieldArrayRemove,
4 | UseFormSetValue,
5 | } from 'react-hook-form'
6 | import { FieldProps } from '@/components/collection-form'
7 |
8 | interface Options {
9 | index: number
10 | fields: FieldProps[]
11 | remove: UseFieldArrayRemove
12 | setValue: UseFormSetValue
13 | }
14 |
15 | function removeFieldsItem({ index, fields, remove, setValue }: Options) {
16 | const field = fields[index]
17 | if (field.existing) {
18 | setValue(`fields.${index}.removed`, true)
19 | return
20 | }
21 |
22 | remove(index)
23 | }
24 |
25 | export default removeFieldsItem
26 |
--------------------------------------------------------------------------------
/admin/src/lib/request-status.ts:
--------------------------------------------------------------------------------
1 | type RequestStatus = 'idle' | 'in-progress' | 'success' | 'failed'
2 |
3 | export default RequestStatus
4 |
--------------------------------------------------------------------------------
/admin/src/lib/schema-from-fields.ts:
--------------------------------------------------------------------------------
1 | import type { FieldProps } from '@/components/collection-form'
2 | import { definitionFromField } from './definition-from-field'
3 |
4 | function schemaFromFields(fields: FieldProps[]) {
5 | const schema: Record = {}
6 | for (const field of fields) {
7 | if (field.removed) {
8 | continue
9 | }
10 |
11 | const [name, definition] = definitionFromField(field)
12 |
13 | if (definition.type === 'string') {
14 | if (definition.enum) {
15 | if (definition.enum.length === 0) {
16 | // remove empty enum list
17 | definition.enum = undefined
18 | } else {
19 | // eslint-disable-next-line @typescript-eslint/ban-ts-comment
20 | // @ts-ignore
21 | definition.enum = definition.enum.map((it) => it.text)
22 | }
23 | }
24 | }
25 |
26 | schema[name] = definition
27 | }
28 |
29 | return schema
30 | }
31 |
32 | export { schemaFromFields }
33 |
--------------------------------------------------------------------------------
/admin/src/lib/slugify.ts:
--------------------------------------------------------------------------------
1 | function slugify(text: string, mangle = false) {
2 | let slug = text
3 | .toString()
4 | .toLowerCase()
5 | .trim()
6 | .replace(/\s+/g, '-')
7 | .replace(/&/g, '-and-')
8 | .replace(/[^\w\-]+/g, '')
9 | .replace(/\-\-+/g, '-')
10 |
11 | if (mangle) {
12 | slug += `-${Math.random().toString(36).substring(2, 7)}`
13 | }
14 |
15 | return slug
16 | }
17 |
18 | export { slugify }
19 |
--------------------------------------------------------------------------------
/admin/src/lib/snacks.ts:
--------------------------------------------------------------------------------
1 | import React from 'preact/compat'
2 | import randomStr from './random-str'
3 | import { signal } from '@preact/signals'
4 |
5 | interface Snack {
6 | id: string
7 | type: 'success' | 'error' | 'neutral' | 'custom'
8 | content: string | React.ReactNode
9 | duration: number
10 | }
11 |
12 | const snacks = signal([])
13 |
14 | function addSnack(snack: Omit) {
15 | const id = randomStr(6)
16 | snacks.value = [...snacks.value, { ...snack, id }]
17 |
18 | setTimeout(() => {
19 | removeSnack(id)
20 | }, snack.duration)
21 |
22 | return id
23 | }
24 |
25 | function removeSnack(id: string) {
26 | snacks.value = snacks.value.filter((snack) => snack.id !== id)
27 | }
28 |
29 | export { addSnack, removeSnack, snacks }
30 |
--------------------------------------------------------------------------------
/admin/src/lib/use-color-scheme.ts:
--------------------------------------------------------------------------------
1 | import React from 'preact/compat'
2 |
3 | type ColorScheme = 'light' | 'dark'
4 |
5 | function useColorScheme() {
6 | const [scheme, setScheme] = React.useState('light')
7 |
8 | React.useEffect(() => {
9 | const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
10 |
11 | if (mediaQuery.matches) {
12 | setScheme('dark')
13 | }
14 |
15 | const listener = (e: MediaQueryListEvent) => {
16 | if (e.matches) {
17 | setScheme('dark')
18 | } else {
19 | setScheme('light')
20 | }
21 | }
22 |
23 | mediaQuery.addEventListener('change', listener)
24 |
25 | return () => {
26 | mediaQuery.removeEventListener('change', listener)
27 | }
28 | }, [])
29 |
30 | return scheme
31 | }
32 |
33 | export { useColorScheme }
34 |
--------------------------------------------------------------------------------
/admin/src/main.tsx:
--------------------------------------------------------------------------------
1 | import './index.css'
2 | import './extras.css'
3 | import { App } from './app.tsx'
4 | import { render } from 'preact'
5 |
6 | render(, document.getElementById('app') as HTMLElement)
7 |
--------------------------------------------------------------------------------
/admin/src/mangobase-app.ts:
--------------------------------------------------------------------------------
1 | import App from './client/app'
2 |
3 | const app = new App(import.meta.env.VITE_API_URL || '/api')
4 |
5 | export default app
6 |
--------------------------------------------------------------------------------
/admin/src/pages/collections/[name]/_layout.tsx:
--------------------------------------------------------------------------------
1 | import {
2 | LoaderFunctionArgs,
3 | NavLink,
4 | Outlet,
5 | useLoaderData,
6 | } from 'react-router-dom'
7 | import AppError from '@/lib/app-error'
8 | import Chip from '@/components/chip'
9 | import Copy from '@/components/copy'
10 | import { DevDialog } from '@/components/dev-dialog'
11 | import { Popover } from '@/components/popover'
12 | import { RouteData } from '.'
13 | import app from '../../../mangobase-app'
14 | import clsx from 'clsx'
15 |
16 | function Component() {
17 | const { collection } = useLoaderData() as RouteData
18 |
19 | const links = [
20 | {
21 | href: '',
22 | icon: 'table_rows',
23 | title: 'Records',
24 | },
25 | {
26 | href: 'hooks',
27 | icon: 'phishing',
28 | title: 'Hooks',
29 | },
30 | {
31 | href: `/logs/?label[$startswith]=/api/${collection.name}`,
32 | icon: 'bug_report',
33 | title: 'Logs',
34 | },
35 | {
36 | href: 'edit',
37 | icon: 'stylus',
38 | title: 'Edit',
39 | },
40 | ]
41 |
42 | const path = `/api${collection.exposed ? '/' : '/_x/'}${collection.name}`
43 | const endpoint = `${window.location.protocol}//${window.location.host}${path}`
44 |
45 | return (
46 | ]
47 |
114 |
115 |
116 |
117 |
118 |
Collections
55 |
61 |
62 |
63 |
71 |
72 |
81 |
82 |
83 |
84 | }
85 | >
86 |
87 |
88 | )
89 | }
90 |
91 | const loader = async () => {
92 | try {
93 | // [ ]: move away from using signals for state management
94 | await loadSchemaRefs()
95 | await loadCollections()
96 | return null
97 | } catch (err) {
98 | throw new AppError((err as any).message, err)
99 | }
100 | }
101 |
102 | export { Component, loader }
103 |
--------------------------------------------------------------------------------
/admin/src/pages/login.tsx:
--------------------------------------------------------------------------------
1 | import { FieldValues, useForm } from 'react-hook-form'
2 | import AVATAR_COLORS from '@/lib/avatar-colors'
3 | import Avatar from 'boring-avatars'
4 | import Button from '@/components/button'
5 | import Input from '@/components/input'
6 | import React from 'preact/compat'
7 | import RequestStatus from '@/lib/request-status'
8 | import { addSnack } from '@/lib/snacks'
9 | import app from '../mangobase-app'
10 | import { useNavigate } from 'react-router-dom'
11 |
12 | function Login() {
13 | const { handleSubmit, register, watch } = useForm()
14 | const [username, setUsername] = React.useState('')
15 | const [isNewEnv, setIsNewEnv] = React.useState(false)
16 | const [status, setStatus] = React.useState('idle')
17 |
18 | const navigate = useNavigate()
19 |
20 | const nameChangeTime = React.useRef>()
21 |
22 | async function login(form: FieldValues) {
23 | setStatus('in-progress')
24 | try {
25 | if (isNewEnv) {
26 | await app.req.post('users', {
27 | ...form,
28 | fullname: form.username,
29 | role: 'dev',
30 | })
31 | }
32 |
33 | const { data } = await app.req.post('login', { ...form })
34 | app.set('auth', data)
35 |
36 | navigate('/collections', { replace: true })
37 | } catch (err: any) {
38 | setStatus('failed')
39 | const message = err?.data
40 | ? err.data.error
41 | : err.message || 'failed to login. check logs or try again!'
42 |
43 | addSnack({ content: message, duration: 2500, type: 'error' })
44 | }
45 | }
46 |
47 | const $username = watch('username')
48 | React.useEffect(() => {
49 | clearTimeout(nameChangeTime.current)
50 | nameChangeTime.current = setTimeout(() => {
51 | setUsername($username)
52 | }, 1000)
53 | }, [$username])
54 |
55 | React.useEffect(() => {
56 | app.req.get('_dev/dev-setup').then((res) => setIsNewEnv(!res.data))
57 | }, [])
58 |
59 | return (
60 |
113 | )
114 | }
115 |
116 | export default Login
117 |
--------------------------------------------------------------------------------
/admin/src/pages/logs.tsx:
--------------------------------------------------------------------------------
1 | import logs, { Log, loadLogStats, loadLogs, logStats } from '@/data/logs'
2 | import BarChart from '@/components/chart'
3 | import Chip from '@/components/chip'
4 | import CleanDate from '@/components/date'
5 | import FilterInput from '@/components/filter-input'
6 | import React from 'preact/compat'
7 |
8 | function Component() {
9 | React.useEffect(() => {
10 | loadLogs()
11 | loadLogStats()
12 | }, [])
13 |
14 | return (
15 |
16 |
Logs
17 |
18 |
19 |
20 | ({
22 | x: new Date(value._id).getHours().toString(),
23 | y: value.requests,
24 | }))}
25 | />
26 |
27 |
28 |
29 |
30 |
31 |
32 | | Date |
33 | Category |
34 | Label |
35 | Status |
36 | Time |
37 |
38 |
39 |
40 |
41 | {logs.value.map((log) => (
42 |
46 | |
47 |
48 | |
49 |
50 | {log.category}
51 | |
52 |
53 |
54 | |
55 |
56 |
57 | |
58 |
59 | {typeof log.time === 'number' ? `${log.time}ms` : ''}
60 | |
61 |
62 | ))}
63 |
64 |
65 |
66 |
82 | {status}
83 |
84 |
85 | )
86 | }
87 |
88 | return (
89 |
90 | {status}
91 |
92 |
93 | )
94 | }
95 |
96 | interface LogContentProps {
97 | log: Log
98 | }
99 |
100 | function LogContent({ log }: LogContentProps) {
101 | const [expanded, setExpanded] = React.useState(false)
102 |
103 | return (
104 |
105 |
106 | {log.label}{' '}
107 | {log.data && (
108 |
117 | )}
118 |
119 |
120 | {expanded && (
121 |
122 | {JSON.stringify(log.data, null, 2)}
123 |
124 | )}
125 |
4 |
5 |
6 | join_right
7 |
8 |
It's not clear what should be here.
9 |
You must be missing.
10 |
11 |
— The Router
12 |
13 |
13 |
Devs
14 |
15 | Accounts with developer permissions for the app
16 |
17 |
18 |
19 | {appDevelopers.value.map((dev) => {
20 | return (
21 |
22 |
27 |
28 |
29 | @
30 | {dev.username}
31 |
32 |
33 | )
34 | })}
35 |
36 |
4 |
Your profile
5 |
6 | To edit your profile, use the /users endpoint in the
7 | meantime.
8 |
9 |
12 |
13 |
14 | reply
15 |
16 |
17 | Expand Validations Schema and select a schema name to view or edit.
18 |
19 |
20 |
21 |
24 |
25 |
26 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
15 |
--------------------------------------------------------------------------------
/website/.vitepress/theme/styles.css:
--------------------------------------------------------------------------------
1 | @media (max-width: 960px) {
2 | .VPHero .image {
3 | opacity: 0;
4 | margin-top: -260px;
5 | }
6 | }
7 |
8 | .hidden {
9 | display: none;
10 | }
11 |
--------------------------------------------------------------------------------
/website/api/index.md:
--------------------------------------------------------------------------------
1 | # Modules
--------------------------------------------------------------------------------
/website/generate-api.mjs:
--------------------------------------------------------------------------------
1 | import fs from 'fs/promises'
2 | import fsSync from 'fs'
3 | import typedoc, { Comment } from 'typedoc'
4 |
5 | const projects = ['base', 'express-server', 'bun-server', 'mongo-db']
6 |
7 | const apiDocPaths = []
8 |
9 | const SKIP_KINDS = [typedoc.ReflectionKind.TypeAlias]
10 |
11 | async function generateApis() {
12 | for (const projectDir of projects) {
13 | const app = await typedoc.Application.bootstrap({
14 | entryPoints: [`../${projectDir}/src/index.ts`],
15 | exclude: ["**/*+(.spec|.test).ts"],
16 | tsconfig: `../${projectDir}/tsconfig.build.json`,
17 | excludePrivate: true,
18 | })
19 |
20 | console.log('[-] Parsing ' + projectDir + '...')
21 |
22 | const pkg = JSON.parse(
23 | await fs.readFile(`../${projectDir}/package.json`, { encoding: 'utf-8' })
24 | )
25 |
26 | const group = {
27 | collapsed: true,
28 | text: pkg.name,
29 | items: [],
30 | }
31 |
32 | try {
33 | await fs.mkdir(`./api/${projectDir}/`)
34 | } catch (err) {
35 | //
36 | }
37 |
38 | const project = await app.convert()
39 | if (project) {
40 | project.traverse((node) => {
41 | if (SKIP_KINDS.includes(node.kind)) {
42 | return
43 | }
44 |
45 | console.log(' * ', `${node.name}.md`)
46 | let path = `/api/${projectDir}/${node.name}`
47 |
48 | if (node.name[0] === node.name[0].toLocaleLowerCase()) {
49 | // doing this because some function names clashed with interface/class
50 | // names, causing an override of content.
51 | path = `/api/${projectDir}/${node.name}_function`
52 | }
53 |
54 | group.items.push({
55 | text: node.name,
56 | link: path,
57 | })
58 |
59 | fsSync.writeFileSync(`.${path}.md`, composeDoc(node, projectDir), {
60 | encoding: 'utf-8',
61 | })
62 | })
63 | }
64 |
65 | group.items.sort((a, b) => (a.text > b.text ? 1 : -1))
66 |
67 | apiDocPaths.push(group)
68 | }
69 | }
70 |
71 | generateApis().then(() => {
72 | console.log('[x] Completed API generation')
73 | fsSync.writeFileSync(
74 | '.vitepress/api-paths.json',
75 | JSON.stringify(apiDocPaths, null, 2)
76 | )
77 | })
78 |
79 | function composeDoc(node, packagePath) {
80 | const urlGenerator = (ref) => urlTo(ref, packagePath)
81 |
82 | const content = [
83 | `# ${node.name}`,
84 | `${typedoc.ReflectionKind.singularString(node.kind)}`,
85 | ]
86 |
87 | if (node.comment) {
88 | content.push(Comment.displayPartsToMarkdown(node.comment.summary, urlGenerator))
89 | }
90 |
91 | node.traverse((innerNode) => {
92 | // [ ] Show signature if any
93 | // [ ] Show item type (string, number, etc.)
94 | if (SKIP_KINDS.includes(innerNode.kind)) {
95 | return
96 | }
97 |
98 | const innerContent = []
99 |
100 | innerContent.push(`## ${innerNode.name}`)
101 | if (innerNode.comment) {
102 | innerContent.push(
103 | Comment.displayPartsToMarkdown(innerNode.comment.summary, urlGenerator)
104 | )
105 | }
106 |
107 | switch (innerNode.kind) {
108 | case typedoc.ReflectionKind.Method: {
109 | innerNode.signatures.forEach((signature) => {
110 | const parameters = []
111 |
112 | for (const p of signature.parameters) {
113 | parameters.push(
114 | `${p.name}: ${typedoc.ReflectionKind.singularString(p.kind)}`
115 | )
116 | }
117 |
118 | const signatureCode = `
119 | \`\`\`typescript
120 | public ${signature.name}(${parameters.join(', ')}): Promise
121 | \`\`\`
122 | `
123 | innerContent.push(signatureCode)
124 |
125 | if (signature.hasComment()) {
126 | innerContent.push(
127 | Comment.displayPartsToMarkdown(signature.comment.summary, (ref) =>
128 | urlTo(ref, packagePath)
129 | )
130 | )
131 | }
132 | })
133 | }
134 | }
135 |
136 | content.push(innerContent.join('\n'))
137 | })
138 |
139 | return content.join('\n\n')
140 | }
141 |
142 | function urlTo(ref, base) {
143 | const parts = []
144 | parts.push(ref.name)
145 |
146 | let parent = ref.parent
147 | while (parent) {
148 | parts.push(parent.name)
149 | parent = parent.parent
150 | }
151 |
152 | parts.reverse()
153 | parts.shift()
154 |
155 | return `/api/${base}/` + parts.join('#')
156 | }
157 |
--------------------------------------------------------------------------------
/website/guide/authentication.md:
--------------------------------------------------------------------------------
1 | # Authentication
2 |
3 | Mangobase comes with a basic built-in authentication [plugin](/guide/plugins). It provides a simple way to register and authenticate users.
4 |
5 | To create a new user, you make a `POST` (aka `create`) request to the `/api/users` endpoint with body:
6 |
7 | ```json
8 | {
9 | "email": "carlson@gmail.com",
10 | "username": "carlson",
11 | "password": "gocarl"
12 | }
13 | ```
14 |
15 | You can then login by making a `POST` request to `/api/login` with body:
16 |
17 | ```json
18 | {
19 | "username": "carlson",
20 | // or "email": "carlson@gmail",
21 | "password": "gocarl"
22 | }
23 | ```
24 |
25 | You get a response in the format:
26 |
27 | ```json
28 | {
29 | "user": {
30 | "id": "5f1e5a8b9d6b2b0017b4e6b1",
31 | "username": "carlson",
32 | "email": "carlson@gmail.com",
33 | },
34 | "auth": {
35 | "type": "Bearer",
36 | "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
37 | }
38 | }
39 | ```
40 |
41 | When making authenticated requests using the built-in method, you add an `Authorization` header with the value `${auth.type} ${auth.token}`.
42 |
43 | ## Custom authentication
44 |
45 | You can choose to implement your own authentication process, like using an auth library or service. To do this, you can create a [plugin](/guide/plugins). See this [implementation](https://github.com/blackmann/mangobase/blob/de9281da1e840ed28acbf715f8417f29b3da56dc/base/src/authentication.ts#L115) as a reference.
46 |
--------------------------------------------------------------------------------
/website/guide/context.md:
--------------------------------------------------------------------------------
1 | # Context
2 |
3 | Context describes a single request to the app. After processing a request, the app returns a context containing a [`result`](/api/base/Context#result).
4 |
5 | How _processing_ works is described as a pipeline. A pipeline runs in the following sequence:
6 |
7 | 1. Runs all `before` hooks [in sequence] installed on the app
8 | 1. Runs all `before` hooks [in sequence] installed on the service
9 | 1. Passes `context` to the service to handle.
10 | 1. The result from the service is passed [in sequence] to all `after` hooks installed on the service
11 | 1. Runs all `after` hooks [in sequence] installed on the app
12 |
13 | The current state of the context is passed with every call to a hook in the pipeline or the service.
14 |
15 | ::: info
16 | Subsequent `before` hooks stop executing the moment `context.result` is set to a non-null value, then skips the service and proceeds with all `after` hooks.
17 | :::
18 |
19 | See the structure of a context [here](/api/base/Context).
20 |
21 | A context is normally created by the [server](/guide/server-adapters) and passed to the app with [`app.api(ctx)`](/api/base/App#api)
22 |
23 | ## Methods
24 |
25 | In Mangobase, the following methods are used. It exists in the context as `ctx.method`.
26 |
27 | ### create
28 |
29 | The equivalent HTTP method is `POST`. It is used to create a new resource. When you make a `POST` request to `/songs` for example, this is a `create` request.
30 |
31 | Using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), this will look like:
32 |
33 | ```javascript{7}
34 | // The API endpoint is [conventionally] prefixed with `/api`
35 | const data = {
36 | title: 'Hello',
37 | artist: 'Adele',
38 | }
39 |
40 | fetch('/api/songs', {
41 | method: 'POST',
42 | body: JSON.stringify(data),
43 | })
44 | ```
45 |
46 | A successful call to `create` will return a `201` status code with the created resource in the response body.
47 |
48 | ### find
49 |
50 | The equivalent HTTP method is `GET`. It is used to retrieve a list of resources. A `GET` request to `/songs` for example is a `find` request. This method is intended to always return a paginated response in the following format:
51 |
52 | ```typescript
53 | interface PaginatedResponse {
54 | data: any[]
55 | total: number
56 | limit: number
57 | skip: number
58 | }
59 | ```
60 |
61 | In frontend code, this will look like:
62 |
63 | ```javascript
64 | fetch('/api/songs', {
65 | method: 'GET',
66 | })
67 | ```
68 |
69 | The response will look like:
70 |
71 | ```json
72 | {
73 | "data": [
74 | {
75 | "id": 1,
76 | "title": "Hello",
77 | "artist": "Adele"
78 | },
79 | {
80 | "id": 2,
81 | "title": "Someone Like You",
82 | "artist": "Adele"
83 | }
84 | ],
85 | "total": 2,
86 | "limit": 10,
87 | "skip": 0
88 | }
89 | ```
90 |
91 | If you wanted to limit the number of items returned, you can pass a `limit` query parameter. For example, `/songs?$limit=1` will return only one item.
92 |
93 | Pagination is done using the `skip` query parameter. For example, `/songs?$skip=5` will skip the first 5 items.
94 |
95 | :::info
96 | You may notice a `$` prefix on the query parameter. This is to prevent conflicts with the fields of a collection. For example, if you have a `limit` field on your collection, you can make a request to `/?limit=100km&$limit=3` _find_ items with a limit of 100km but only return 3 items.
97 | :::
98 |
99 | ### get
100 |
101 | Making a `GET` request to `/songs/1` for example is `get`. This method is intended to always return a single item.
102 |
103 | In frontend code, this will look like:
104 |
105 | ```javascript
106 | fetch('/api/songs/1', {
107 | method: 'GET',
108 | })
109 | ```
110 |
111 | A status code of `404` will be returned if the item is not found.
112 |
113 | ### update
114 |
115 | The equivalent HTTP method is `PATCH`. It is used to update a single resource. For example, when you make a `PATCH` request to `/songs/1`.
116 |
117 | ### remove
118 |
119 | The equivalent HTTP method is `DELETE`. A `DELETE` request to `/songs/1` for example, this is a `remove` request. Note that this requires the `id` of the resource to be passed as a parameter.
120 |
121 | :::tip
122 | All these methods can accept a query parameter. For example, with `find`, you can make a GET `/songs?title=hello` request to search for songs with the title `hello`.
123 | :::
124 |
125 | ## Invalid requests
126 |
127 | As far as Mangobase is concerned, some requests like the following are not supported:
128 |
129 | - POST `/songs/1` - You cannot create an item on a detail path.
130 | - PATCH `/songs` - You cannot patch a base path.
131 | - DELETE `/songs` - You cannot delete a base path.
132 | - PUT - Mangobase does not support `PUT` requests.
133 |
--------------------------------------------------------------------------------
/website/guide/dashboard.md:
--------------------------------------------------------------------------------
1 | # Dashboard
2 |
3 | The dashboard is central to how you use Mangobase. It offers a very intuitive experience.
4 |
5 | ## Collections
6 |
7 | This page is where you see all your collections, add new ones or edit existing ones. Selecting a collection allows you to see all the data that has been created (in a paginated format).
8 |
9 | It also provides a filter/query input to help you search for specific data.
10 |
11 | :::info
12 | The query filter, at the moment, is a work-in-progress
13 | :::
14 |
15 | ### Hooks editor
16 |
17 | The hooks editor allows you to compose before and after hooks for your collection's service. It is a very intuitive and creative way to extend the functionality of your service.
18 |
19 | You can select from a number of pre-installed plugin hooks or [write your own](/guide/hooks#registering-a-plugin-hook).
20 |
21 | See [hooks](/guide/hooks) for more information. Below is a video demonstrating how to use the hooks editor.
22 |
23 |
24 |
25 | ## Logs
26 |
27 | There is a page to show request logs. When a request is not _ok_, the error data is logged and you can see it here.
28 |
29 | ## Settings
30 |
31 | The settings page allows you to configure your app. At the moment, it only shows the developers added to the project and your profile.
32 |
--------------------------------------------------------------------------------
/website/guide/database-adapters.md:
--------------------------------------------------------------------------------
1 | # Database adapters
2 |
3 | Mangobase is designed to be database agnostic. This means you can implement any [Database](/api/base/Database) for your app. However, there's an official support for just Mongo at the moment.
4 |
5 | :::info
6 | You're welcome to author a database adapter for your favorite database and share with the community. [Here](https://github.com/blackmann/mangobase/blob/master/mongo-db/src/mongodb.ts) is an implementation of the MongoDb adapter.
7 | :::
8 |
--------------------------------------------------------------------------------
/website/guide/deployment.md:
--------------------------------------------------------------------------------
1 | # Deployment
2 |
3 | :::warning
4 | It's not advisable to make changes to schemas, hooks, or other configuration in production. If you need to make changes, it's best to do so in a development environment and then deploy the changes to production.
5 | :::
6 |
7 | ## Dokku
8 |
9 | If you boostrapped the app with the CLI, you can deploy to your Dokku instance/app with the following command:
10 |
11 | ```bash
12 | git push dokku master
13 | ```
14 |
15 | :::info
16 | Dokku is a self-hosted Heroku alternative. You can read more about it [here](https://dokku.com).
17 | :::
18 |
19 | Set the proxy port if your app is not receiving requests:
20 |
21 | ```bash
22 | dokku ports:set http:80:5000
23 | ```
24 |
25 | ## Docker-based deploys
26 |
27 | You can deploy your Mangobase app using Docker. When you use the [Mangobase CLI](/guide/getting-started#starting-a-new-project), it will generate a `Dockerfile` for you. You can then build and run the Docker image:
28 |
29 | ```bash
30 | $ docker build -t my-mangobase-app .
31 | $ docker run -p 8000:5000 my-mangobase-app --env=SECRET_KEY=xA90boi2 --env=DATABASE_URL=mongodb://host.docker.internal:27017/mangobase-app-db
32 | ```
33 |
34 | ## Deploying to Heroku
35 |
36 | Add a `heroku.yml` file with the following content:
37 |
38 | ```yaml
39 | build:
40 | docker:
41 | web: Dockerfile
42 | ```
43 |
44 | Then make a `git push` to your project.
45 |
46 | Remember to do set the `SECRET_KEY` and `DATABASE_URL` environment variables in your Heroku app.
47 |
48 | ```bash
49 | $ heroku config:set SECRET_KEY=xA90boi2 DATABASE_URL=mongodb://host.docker.internal:27017/mangobase-app-db
50 | ```
51 |
52 | Or you can use the [Heroku dashboard](https://devcenter.heroku.com/articles/config-vars#using-the-heroku-dashboard) to set the environment variables.
53 |
54 | Read more from [here](https://devcenter.heroku.com/articles/build-docker-images-heroku-yml) on how to deploy Dockerfile based apps to Heroku.
55 |
--------------------------------------------------------------------------------
/website/guide/faqs.md:
--------------------------------------------------------------------------------
1 | # FAQs
2 |
3 | ## Who is this for?
4 |
5 | - Beginners who want to ease into backend development.
6 | - Fronted [focused] developers who want to build a backend for their app.
7 | - Fullstack developers who want to quickly bootstrap a backend for their app without having to write boilerplate code.
8 |
9 | Though Mangobase is low-code and easy to use, it is also very flexible and can be used to build complex applications.
10 |
11 | ## How do I make requests to my API?
12 |
13 | You can use any HTTP client to make requests to your API. For example, you can use [HTTPie](https://httpie.io) or [Postman](https://www.postman.com).
14 |
15 | Inside your frontend app, you can use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or [Axios](https://axios-http.com), etc.
16 |
17 | If you added a collection with name `songs` for example, you can make a `GET` request to `http://localhost:3000/api/songs` to get all songs. You can also make a `POST` request to `http://localhost:3000/api/songs` to create a new song.
18 |
19 | Other ways to interact with your API can be found in [Context methods](/guide/context#methods).
20 |
--------------------------------------------------------------------------------
/website/guide/getting-started.md:
--------------------------------------------------------------------------------
1 | # Getting started
2 |
3 | Mangobase is fundamentally designed to be easy to use while providing a cohesion of developer experience; that said, it's easy to get started.
4 |
5 | :::info
6 | We currently provide a database adapter for Mongo only, so you may need to install [Mongo](https://mongodb.com) to be able to use Mango. You can however implement a custom database adapter for any database of choice. See [database adapters](/guide/database-adapters)
7 | :::
8 |
9 | ## Starting a new project
10 |
11 | You can use the command below to bootstrap a project
12 |
13 | ::: code-group
14 |
15 | ```sh [npm]
16 | $ npm create mango@latest
17 | ```
18 |
19 | ```sh [yarn]
20 | $ yarn create mango
21 | ```
22 |
23 | :::
24 |
25 | ## Adding to an existing project
26 |
27 | You can add Mango to any existing project. At the moment, [@mangobase/express](/guide/server-adapters#express) and [@mangobase/bun](/guide/server-adapters#bun) are the officially supported server adapters. You can add Mango to your project in a few easy steps if you're using any of those frameworks.
28 |
29 | Otherwise, you can implement a custom adapter for your project. See [implement a custom server adapter](/guide/server-adapters#other-servers)
30 |
31 | :::tip
32 | Reference the [examples](https://github.com/blackmann/mangobase/tree/master/examples) on how to set up your project.
33 | :::
34 |
--------------------------------------------------------------------------------
/website/guide/index.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | ::: warning
4 | Mango is still under heavy development; it's not advisable to use this for a production app as the API/design may change rapidly. You can however try it on side projects and proof-of-concepts.
5 | :::
6 |
7 | Mango (short for Mangobase) is a Javascript low-code backend framework for building [RESTful](rest.md) applications. Given that REST apps follow a convention on how to treat data, Mango provides the following benefits:
8 |
9 | - Reduces boilerplate for creating services for data models
10 | - Performs schema validation
11 | - Handles errors
12 | - Provides convenient querying mechanisms
13 |
14 | When building REST backends, it's ubiquitous that you implement all of these features and some. Mango takes care of all of those.
15 |
16 | ::: tip
17 | Being a low-code framework, you get to write code too, though a lot of things have been taken care of for you.
18 | :::
19 |
20 | ## How it works
21 |
22 | A Mangobase app works by accepting a [`context`](/guide/context) from a server (like express, bun, etc.), processing it and returning a `context` back.
23 |
24 | To demonstrate with code, this is how it looks like:
25 |
26 | :::warning
27 | Just so it's not misleading, you wouldn't write any of the code demonstrated below. It's only an illustration (with code) about how it works.
28 | :::
29 |
30 | ```javascript{5,12,15}
31 | const mangobaseApp = new App({})
32 | const app = express()
33 |
34 | app.get(['/songs', '/songs/:id'], async (req, res) => {
35 | // create context
36 | const context = {
37 | path: req.path,
38 | headers: req.headers,
39 | // ... other properties here
40 | }
41 |
42 | // pass context to Mangobase and get result and statusCode back
43 | const { result, statusCode} = await app.api(context)
44 |
45 | // send response with express
46 | res.status(statusCode).json(result)
47 | })
48 | ```
49 |
50 | But with Mangobase, you don't have to do any of those. That was just a demonstration of the process looks like.
51 |
52 | If it wasn't clear, Mangobase only processes a context and does not deal with how an http request comes in or how a response is sent.
53 | This allows Mangobase to be able to work with any server (express, bun, nestjs, etc. etc.)
54 |
55 | ### Mangobase Project
56 |
57 | A Mangobase projects combines a database adapter and a server adapter to handle RESTful requests. You can bootstrap a Mangobase project using the [CLI](/guide/getting-started). The code generated by the CLI may be all you may ever need.
58 |
59 | You will spend the rest of your time in the dashboard (which runs in the browser) preparing your resource schema and setting up hooks.
60 |
61 | ### Dashboard
62 |
63 | Mangobase ships with a dashboard to allow you view your data, create collections, configure hooks and more. See [dashboard](/guide/dashboard).
64 |
--------------------------------------------------------------------------------
/website/guide/plugins.md:
--------------------------------------------------------------------------------
1 | # Plugins
2 |
--------------------------------------------------------------------------------
/website/guide/query.md:
--------------------------------------------------------------------------------
1 | # Paths and Queries
2 |
3 | This document describes how paths and query parameters are treated in Mangobase.
4 |
5 | ## Paths
6 |
7 | When you add a collection with name `tasks` (from the dashboard), a service is registered to handle requests to `/tasks` and `/tasks/:id` paths.
8 |
9 | See [context methods](/guide/context#methods) for the different methods (HTTP method + paths) that can be used to interact with the service.
10 |
11 | ## Queries
12 |
13 | Queries are standardized to match the fields of a collection's schema. Therefore, if you have a schema for `users` collection with the following structure:
14 |
15 | ```json
16 | {
17 | "name": { "type": "string" },
18 | "age": { "type": "number" },
19 | "address": {
20 | "type": "object",
21 | "schema": {
22 | "city": { "type": "string" },
23 | "houseNumber": { "type": "string" },
24 | "state": { "type": "string" }
25 | }
26 | }
27 | }
28 | ```
29 |
30 | We can perform the following filter
31 |
32 | ``` javascript
33 | '/users?name=Not+Gr' // gets all users with name == 'Not Gr'
34 | '/users?age[$gt]=17&address.city=Accra' // get all users above 17 years of age and live Accra
35 | ```
36 |
37 | You may notice that there's a [pattern](/guide/rest) between the query parameters and the fields of the schema
38 |
39 | ### Query operators
40 |
41 | As you may have already noticed from the example above, there is an operator `$gt` used. These are special operators that allow us
42 | to perform advanced queries beside simple equality check.
43 |
44 | :::info
45 | These query operators are converted to the right filter and query by the database adapters.
46 | :::
47 |
48 | Lets talk about them:
49 |
50 | #### $gt/gte
51 |
52 | `/users?age[$gt]=17` - gets all users above 17 years of age
53 |
54 | `/users?age[$gte]=17` - gets all users above or equal to 17 years of age
55 |
56 | This query operator works for fields of number and date types.
57 |
58 | #### $lt/lte
59 |
60 | `/users?age[$lt]=17` - gets all users below 17 years of age
61 |
62 | `/users?age[$lte]=17` - gets all users below or equal to 17 years of age
63 |
64 | :::tip
65 | If you wanted to get all users between 17 and 20 years of age, you can combine the two operators like so:
66 |
67 | `/users?age[$gt]=17&age[$lt]=20`
68 | :::
69 |
--------------------------------------------------------------------------------
/website/guide/server-adapters.md:
--------------------------------------------------------------------------------
1 | # Server adapters
2 |
3 | You can use Mango with any server of choice. This is possible because the core tries to be agnostic of transport mechanisms or server implementations and uses [`contexts`](/guide/context) instead.
4 |
5 | This way, servers can form a context, pass it to [`app.api()`](/api/base/App#api) and then get a context back. With this result, the server can use it to form a response per its design.
6 |
7 | Mango, however, offers server implementations for Express and Bun. But you can be able to [implement a server](#other-servers) for any Javascript framework. _It's actually very easy._
8 |
9 | ## Express
10 |
11 | For express servers, install [@mangobase/express](https://www.npmjs.com/package/@mangobase/express)
12 |
13 | ```bash
14 | yarn add express @mangobase/express
15 | ```
16 |
17 | Usage example:
18 |
19 | ```javascript{2,5}
20 | import { App } from 'mangobase'
21 | import expressServer from '@mangobase/express'
22 |
23 | const app = new App({})
24 | app.serve(expressServer).listen(4000)
25 | ```
26 |
27 | ### Existing projects
28 |
29 | If you're adding Mangobase to an existing project, or need more control over the express app instance, you can do the following instead:
30 |
31 | ```javascript
32 | import { App } from 'mangobase'
33 | import express from 'express'
34 | import { withExpress } from '@mangobase/express'
35 |
36 | const app = new App({})
37 | let expressApp = express()
38 |
39 | // do stuff with `expressApp` as usual, like add middleware, etc.
40 |
41 | expressApp = app.serve(withExpress(expressApp, app))
42 |
43 | // do more stuff with `expressApp` ...
44 |
45 | expressApp.listen(4000)
46 | ```
47 |
48 | ## Bun
49 |
50 | Mango works with [bun](https://bun.sh) too.
51 |
52 | To use Mango with Bun, install [@mangobase/bun](https://www.npmjs.com/package/@mangobase/bun)
53 |
54 | Usage example:
55 |
56 | ```typescript
57 | import { App } from 'mangobase'
58 | import { bunServer } from '@mangobase/bun'
59 |
60 | const app = new App({})
61 |
62 | app.serve(bunServer(4000))
63 | ```
64 |
65 | ## Other servers
66 |
67 | If you're using other frameworks other than `express` or `Bun`, you can still use Mango but you'll have to implement an adapter to create and handle contexts for Mangobase [`App`](/api/base/App).
68 |
69 | This involves only a few lines of code. You can reference the implementation for express here: https://github.com/blackmann/mangobase/blob/master/express-server/src/index.ts
70 |
--------------------------------------------------------------------------------
/website/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | # https://vitepress.dev/reference/default-theme-home-page
3 | layout: home
4 |
5 | title: Home
6 |
7 | hero:
8 | name: "Mangobase"
9 | text: "Low-code Javascript backend framework"
10 | tagline: Build RESTful backend services quickly, with very few concepts to learn
11 | actions:
12 | - theme: brand
13 | text: Get started
14 | link: /guide/getting-started
15 | - theme: alt
16 | text: API Reference
17 | link: /api/
18 |
19 | features:
20 | - title: Amazing UI
21 | icon: ❇️
22 | details: You get a free dashboard to create your schema, view your data and configure parts of your project.
23 | - title: Few concepts
24 | icon: ✍🏽
25 | details: You have to know very few concepts to get started with Mangobase. Context, hook and queries.
26 | - title: Add to existing projects
27 | icon: 🚡
28 | details: You can add Mangobase to existing projects
29 | - title: Works with version control
30 | icon: 🏂
31 | details: Changes to your project can be tracked with version control. This allows for transparent collaboration with teams.
32 | ---
33 |
--------------------------------------------------------------------------------
/website/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "website",
3 | "version": "0.0.1",
4 | "scripts": {
5 | "dev": "vitepress dev",
6 | "build": "yarn docs && vitepress build",
7 | "preview": "vitepress preview",
8 | "docs": "node generate-api.mjs",
9 | "clean": "find api/ -mindepth 1 -not -name 'index.md' -exec rm -rf {} +"
10 | },
11 | "devDependencies": {
12 | "typedoc": "^0.25.1",
13 | "vitepress": "^1.0.0-rc.10"
14 | }
15 | }
16 |
--------------------------------------------------------------------------------
18 |