Provide a plugin-like hooks for Marble.js applications about marble HOT 8 CLOSED

Right now Marble.js is trying to reside between library and framework, but if we want to extend the tooling and available features in order to have more coherent place, we should definitely treat it more as a fully featured framework.

Yes, this kind of initialization process is something that we need introduce, but in version 2. Because we want to add a support for web sockets, this thing is required. Without an additional abstraction level, the Marble environment will be too diffused.

@krzysztof-miemiec BTW. @marblejs/cli is a cool idea 🤔

from marble.

I'd like to clarify the request - basically you'd like to be able to subscribe to a stream of general server events?

import { createServer } from 'http'; // or http2;
import { httpListener } from '@marblejs/core';
 
// ...define middlewares, effects, onClose, onError

const app = httpListener({ middlewares, effects });

createServer(app)
      .listen(port, onListen)
      .on('close', onClose) // These are the events you'd like to listen to
      .on('error', onError);

If my assumption above is correct, then we'd have to slightly change the way of initializing the app. My proposal would be to do something like this:

import { createServer } from 'http'; // or http2;
/*
 * Instead of httpListener, we now use "marble", that not only handles
 * http stuff but also the server events (maybe also auto-forking (to run
 * server on multiple threads by default and support for websockets)
 */
import { marble } from '@marblejs/core'; 

// ...define middlewares/effects as before

// type ServerEvent = { type: 'close' } | { type: 'error', error: Error } | { type: 'listening }; // etc.
const serverEvent$ = (serverObservable: Observable<ServerEvent>) => serverObservable.pipe(
  // ... do something with events 
);

// We can now pass "server event handlers" to marble's config
const app = marble({ middlewares, effects, serverEventHandlers: serverEvent$ });

// marble returns a function which accepts standard Node.js net.Server
app(createServer());

This is definitely a breaking change (with the naming) and I'd like to hear @JozefFlakus's input on that. Maybe we should create a separate handler for that, or provide something like create-marble-app that configures that stuff under the hood. I'd personally prefer to have such stuff handled somewhere in the core, assuming that everyone would like to have straightforward support for aforementioned process forking (aka multithreading) and server event streams out of the box.

from marble.

Thanks, @krzysztof-miemiec for the inputs. That is the exactly the requirement. My quest started with this plugin:
https://www.npmjs.com/package/marble-mix
https://github.com/mistyharsh/marble-mix

The solution I have currently is not awkward but can be made more elegant.

from marble.

This issue is just what I've been looking for! We've gotten very interested in Marble.js and I built aws-serverless-marblejs to experiment and pursue that interest.

Now I'm sketching out a new project -- following the lead of marble-mix's Effect Logger -- that componentizes a use to deploy a swagger.yml definition of a Marble.js app. However, as @mistyharsh points out, the Effect graph is not available downstream.

A very basic swagger.yml can be produced by traversing that Effect graph just like marble-mix does. A much richer swagger.yml could result with the help of TypeScript decorators and AST driven inspection of the request/response data types.

Code generation from a swagger.yml is a well-trodden path but not so interesting, I think. Code generation is freighted with all kind of mechanical problems, like repeatability for example, plus the tediousness of having to honor the entire Swagger specification.

The inverse -- from running code to a swagger.yml -- on the other hand would be very useful in terms of automatic service documentation, discovery and sandboxing.

I'm proceeding with my project by hacking the visibility of the Effect graph while watching this issue closely.

Many thanks for a great -- dare I say -- framework!

from marble.

Thanks @mflorence99 for kind words! I see that the community is starting to grow and can't wait to see what you will bring next! 🚀

Regarding swagger support, we have it in our Future ideas board for some time, but didn't have enough time to start working on it. Right now our main focus is to release version 1.3 with improved type inference for @marblejs/middleware-joi and after that we will continue our work on version 2.0 (next). Some time ago we discussed how the support could look like and we took into consideration some ideas from other frameworks like eg. NestJS. In my opinion the way of using TS decorators doesn't fit to functional nature of Marble.js. Thats why we came into an idea of generating blueprints based on test cases (something like test-driven-documentation), which @krzysztof-miemiec mentioned here. It would be a very cool feature but still it is only an idea.

If you would like to discuss the swagger topic then please create dedicated issue. We will discuss there how the integration could look like. 🙂

from marble.

Sweet @JozefFlakus -- I will do just that. I really like what Marble.js does and how you've built it. For now, I'm just experimenting. I'm a million miles from a PR and I'm not trying to box you in or suggest any course for you to follow. If my experiments turn up any ideas, that will be nice, if they don't then I'll set them aside :)

from marble.

@mistyharsh With the introduction of version 2.0, I'm closing this issue and marking it as done.
See version 2.0 documentation for server event hooks.. 🚀

from marble.

@mflorence99 Did you have any luck generating a swagger.yml in your marblejs apps? Any tips you could share here?

from marble.