/**
 * value-object: parse once at the boundary, carry the proof through the type
 * system. Equality and serialisation for free. Data that is meant to carry
 * immutable value, not identity and mutation.
 */
class Email extends ValueObject.define({
  id: 'Email',
  schema: () => z.string().email(),
}) {
  get domain() { return this.props.split('@')[1] }
}

const email = Email.fromJSON('alice@example.com') // throws if invalid
email.domain // 'example.com' -- no re-validation needed downstream
JSON.stringify(email) // '"alice@example.com"' -- round-trips through JSON without losing the type

/**
 * entity: Event-driven domain entities with Zod validation. Define props and
 * events once; get typed mutations, per-mutation rollback on validation
 * failure, a domain event journal, and storage serialisation.
 *
 * For data that is meant to carry identity and mutation.
 */
class Account extends Entity.define(
  { name: 'account', idField: 'accountId', schema: () => z.object({ ... }) },
  [onCreated, onDeposited],
) {}

const account = new Account()
account.mutate('account.created', { name: 'Operating', tenantId: 'tenant-1' })
account.mutate('account.deposited', { amount: 250 })
account.props.balance // 250 -- schema re-validated after every mutation

/**
 * api: define your API in Zod once, then drive your client, server, React Query
 * hooks, and anything else that needs to know the shape of a request or
 * response -- without coupling those layers to each other.
 *
 * Use with value objects to have ergonomic, type-safe APIs with behaviour
 * attached to your data, without sacrificing type safety or runtime
 * validation.
 **/
const accountAPI = {
  getAccount: api.defineEndpoint({
    request: z.object({ accountId: z.number() }),
    response: z.object({ name: z.string() }),
    metadata: { method: 'GET', path: '/accounts/:accountId', somethingElse: '...' },
  }),
}

const router = defineRouter<typeof accountAPI, AppContext>({
  definitions: userAPI,
})
const implemented = router.implement({
  endpoints: {
    getAccount: router
      .endpoint('getAccount')
      .handle(({ context, data }) => context.accountService.findById(data.accountId)),
  },
})
implemented.dispatch({ endpoint: 'getAccount', data: { accountId: 123 } }) // typed request body, typed response body on the server

const client = new APIClient(accountAPI, { resolver: ...} // Typed API client with a customizable resolver

client.request('getAccount', { accountId: 123 }) // typed request body
  .then(account => account.balance) // typed response body




/**
 * faux: deterministic fixtures with complete intellisense. Define model
 * factories with dependency injection and isolated seed management; the same
 * seed always produces the same data. Bring your own test framework and make
 * testing with snapshots or making nonproduction data deterministic a breeze.
 *
 */
const context = faux.defineContext({
  helpers: {
    randomName: ({ seed }) => `User${seed}`,
    randomEmail: ({ seed }) => `user${seed}@example.com`
  }
  shared: () => ({
    timestamp: new Date('2024-01-01')
  })
})

const user = context.defineModel(ctx => ({
  id: ctx.seed,
  name: ctx.helpers.randomName,
  email: ctx.helpers.randomEmail
  createdAt: ctx.shared.timestamp
  // Resolve another model from a different file
  address: ctx.find(address)
}))

const fixtures = context.defineFixtures({ user, ... })

const f = fixtures({ seed: 123, override: { user: { name: 'John' }}})
f.user         // generated on demand, cached for this fixture instance
f.user.address // resolved from its own model, same seed offset every time

/**
 * result: typed sync/async error handling without try/catch noise. What I
 * hoped Promises would be when they were first released. Chain .map(),
 * .mapAsync(), and .tap() seamlessly across sync and async boundaries, with no
 * nesting or boilerplate.
 */
Result.invokeAsync(authorize, req)
  .mapAsync(getPostsForUser)
  .tap(
    posts => res.json({ posts }),
    err   => res.status(500).send('Something went wrong'),
  )

/**
 * optional: monadic Optional<T> for null-safe chaining. Converts seamlessly
 * between async and sync with a similar interface to Result. For cases where
 * the absence of a value is not an error, but you still want to avoid null
 * checks and `?.` noise.
 */
Optional.of(maybeUser)
   .pick('userId')
   .flatMapAsync(getUserSettings)
   .orElse(defaultSettings)