Consider consolidating everything under a single module.

[hayleigh-dot-dev]

Hey this library is a great idea, excited to see someone tackle it! I was checking this out for a project I'm starting and I wanted to suggest some minor change to the api based on existing Gleam idioms/practices.

Typically we consider types modules (aka modules that only contain type definitions) bad practice, and prefer to keep types close to the functions relevant to them. This makes use simpler (I don't have to pull in two modules any time I want to work with json schemas) and makes reference easier (I don't have to jump between two pages to understand the docs).

I'd like to suggest grouping everything under jscheam/schema such that you would do:

import jscheam/schema

let user_schema: schema.Type = schema.object([
  schema.property("name", schema.string()),
  schema.property("age", schema.integer()),
  schema.property("email", schema.string())
])

This establishes a namespace for your package (jscheam) while keeping the api meaningful at the point of use by putting things in a schema module. This pattern is followed by packages like youid where you see youid/uuid.

[Neofox]

Hello thank you for leaving a comment!
I am always open to suggestions especially from someone with this much experience in the language.
I was actually considering moving things around a bit, this seems like a great idea.
I was just worried about the file size with everything in the same folder, this is why I re-exported the type from the property.gleam file into the main entrypoint.

I will have a look at the youid package!

[Neofox]

I created a PR #2 to implement the change, moving the public API into a schema module.

BEFORE

import jscheam

let schema =
  jscheam.object([
    jscheam.prop(
      "profile",
      jscheam.object([
        jscheam.prop("bio", jscheam.string()) |> jscheam.optional(),
        jscheam.prop("avatar_url", jscheam.string()),
      ])
      |> jscheam.disallow_additional_props(),
    ),
  ])
  |> jscheam.disallow_additional_props()

let json = jscheam.to_json(schema) |> json.to_string()

AFTER

import jscheam/schema

let schema =
  schema.object([
    schema.prop(
      "profile",
      schema.object([
        schema.prop("bio", schema.string()) |> schema.optional(),
        schema.prop("avatar_url", schema.string()),
      ])
      |> schema.disallow_additional_props(),
    ),
  ])
  |> schema.disallow_additional_props()

let json = schema.to_json(schema) |> json.to_string()

I just wonder if I should leave everything under the schema namespace or move the properties specific functions under schema/properties and type specific functions under schema/type but it may be overkill and like you said may things harder to find with many sub-modules

[hayleigh-dot-dev]

Hey wicked, thanks for considering this!

just wonder if I should leave everything under the schema namespace or move the properties specific functions under schema/properties and type specific functions under schema/type

I would strongly suggest against this: in Gleam we're okay with big modules! Modules aren't a way to organise code they're a way to enforce boundaries around independent units of code, but nothing is independent here everything is closely tied together.

[Neofox]

I see, makes sense!
I'll make sure everything looks right and will probably release those changes as a v2 in a few hours 😊
Again thank you for your valuable input!

[Neofox]

#2 was merged and released with the tag v2.0.0