hyper nano version is a standalone developer instance of hyper, this version gives you the ability to run hyper locally with no config setup.
A core tenant of the hyper service framework is that an application should not need to care about the underlying service implementation. By building an application to consume an api, your appliation, and ergo your business logic, is kept separate and decoupled from the services that power it.
Learn more about Clean Architecture
This allows for swapping out the service api implementations, without having to change business
logic. hyper-nano
is an embodiment of this approach.
hyper nano
is an instance of hyper running an http
based api, and a set of in-memory
adapters
for all of the hyper service
offerings:
- data (powered by In-Memory MongoDB)
- cache (powered by Sqlite)
- storage (powered by your local file system)
- search (powered by Sqlite and Minisearch)
- queue (powered by Sqlite and an in-memory queue)
This allows running a hyper instance locally, great for development, or for sandboxed short-lived environments ie. GitHub Workspaces or GitPod.
At hyper, we exclusively use short-lived ephermeral environments for all development. We dog food hyper to build hyper.
Then when you deploy, your application consumes your actual hyper application in
hyper cloud, with no code changes required; (hyper cloud is just hyper
instances running a different http
based api set of adapters
)
To use hyper nano
, you can download a compiled binary and run it
curl https://hyperland.s3.amazonaws.com/hyper -o nano
chmod +x nano
./nano
There are binaries built for each major platform:
Alternatively, if you use Node
, you may run hyper nano
using npx
:
npx hyper-nano --domain=foobar --experimental --data --cache ...
Alternatively, if you use Deno
you may run hyper nano
directly from the source:
deno run --allow-run --allow-env --allow-read --allow-write=__hyper__ --allow-net --unstable --no-check=remote https://raw.githubusercontent.com/hyper63/hyper/main/images/nano/mod.js
If you'd like to programmatically start hyper nano
, you can import main.js
and run main
:
import { main } from 'https://raw.githubusercontent.com/hyper63/hyper/main/images/nano/main.js'
await main()
and then run:
deno run --allow-env --allow-read --allow-write=__hyper__ --allow-net --unstable --no-check=remote foo.js
All of these examples above will start a hyper nano
instance, listening on port 6363
. You can
then consume your hyper instance
hyper-connect
(recommended) or
using HTTP
.
To consume using hyper-connect
pass
http://127.0.0.1:[port]/[domain]
to hyper-connect
as your
connection string
Consume with hyper-connect
:
import { connect } from 'hyper-connect'
const hyper = connect('http://127.0.0.1:6363/test')
await hyper.data.list()
Or consume via HTTP
curl http://127.0.0.1:6363/data/test
Starting with Node 17, Node has changed how it resolves
localhost
, when using globalfetch
andfetch
from libraries likeundici
. This may cause requests tolocalhost
not to resolve correctly and fail. To get around this, you can use127.0.0.1
or0.0.0.0
, in lieu oflocalhost
. For more info, See this issue
If you use
hyper-connect
to consume hyper, you may disregard this section.
hyper nano
is built on the open source version of hyper, and has a different URL structure than
hyper cloud
. This is because hyper cloud
allows for groupings of services made explicit by the
url.
For example, assuming the domain foo
that has a data
and cache
service, hyper nano
urls are
structured as /data/foo
and /cache/foo
, whereas hyper cloud
urls are structured as
/foo/data/default
and /foo/cache/default
.
If you're consuming hyper
using straight HTTP, you will need to take this difference in url
structure into account. If you use hyper-connect
, no changes are required since hyper-connect
supports both hyper oss
and hyper cloud
url structures and knows which structure to use based on
the provided connection string.
This feature is experimental and will need the
--experimental
flag to be enabled
hyper nano
can be supplied arguments to create services on startup:
--data
: create a hyper data service on startup--cache
: create a hyper cache service on startup--storage
: createa a hyper storage service on startup
Other command line arguments can be provided:
--purge
: destroy the existing services. You may also pass in which service types to purge. ie./nano --experimental --data --cache --storage --purge=data,cache
will deletedata
andcache
, but notstorage
--domain
: the name of the domain your services will be created under. This defaults totest
Examples:
# Listen on 6363
./nano
# Purge the existing data service, then create a new one in test domain
./nano --experimental --data --purge
# Purge the cache service, then create data and cache services in test domain
./nano --experimental --data --cache --purge=cache
# Purge data, cache, and storage, then create data, cache, and storage services in test domain
./nano --experimental --data --cache --storage --purge
or programmatically:
import { main } from 'https://raw.githubusercontent.com/hyper63/hyper/main/images/nano/main.js'
/**
* - Listen on 6363
* - Purge data service in test domain
* - Create data, cache, and storage services in the test domain
*/
await main({
domain: 'test',
experimental: true,
services: {
data: true,
cache: true,
storage: true,
},
purge: {
data: true,
},
})
deno task cache
deno task test
make clean compile-{target}
Apache 2.0