jsonslice

README

jsonslice

A []any you can persist to a JSON/JSONB column and expose as a gqlgen scalar — without importing gqlgen, lib/pq, or pgx.

JsonSlice is a tiny type with three independent integrations packed in:

Integration	Hooks	Cost to your dependency tree
encoding/json	MarshalJSON / UnmarshalJSON	stdlib
database/sql	Value() / Scan()	stdlib
gqlgen scalar	MarshalGQL / UnmarshalGQL	none — detected by duck typing

The third row is the point. gqlgen recognises any type with the right MarshalGQL(io.Writer) and UnmarshalGQL(any) error method signatures, so we expose the methods without importing github.com/99designs/gqlgen. Consumers who don't use gqlgen pay nothing.

Install

go get github.com/ubgo/jsonslice

Use

import "github.com/ubgo/jsonslice"

type Event struct {
    ID   string
    Tags jsonslice.JsonSlice  // ["urgent", "billing", 42]
}

// Save → JSON column
db.Exec(`INSERT INTO events(id, tags) VALUES (?, ?)`, e.ID, e.Tags)

// Load
var loaded Event
db.QueryRow(`SELECT id, tags FROM events WHERE id = ?`, "x").
    Scan(&loaded.ID, &loaded.Tags)

In a gqlgen gqlgen.yml:

models:
  JSON:
    model: github.com/ubgo/jsonslice.JsonSlice

Behaviour

• null is preserved. A nil slice marshals to null; the JSON value null deserialises back to a nil slice. An empty non-nil slice marshals to [].
• Scan accepts []byte, string, or nil. Anything else returns an error. Empty bytes scan to nil.
• MarshalGQL does not panic. Encoding errors fall back to writing [] rather than panicking inside a request goroutine.

License

Apache-2.0 — see LICENSE.

Documentation

Overview

Package jsonslice is a JSON-backed slice type that round-trips through SQL columns and GraphQL scalars without dragging gqlgen or any database driver into the dependency graph.

The core type is JsonSlice, an alias for []any that:

• Marshals/unmarshals as a JSON array via the standard encoding/json interfaces.
• Implements sql.Scanner and driver.Valuer so it can be stored in a JSON / JSONB column directly.
• Implements MarshalGQL/UnmarshalGQL so gqlgen will pick it up as a custom scalar via duck typing — no gqlgen import is required, and consumers that don't use gqlgen pay nothing.

The zero value is an empty slice. nil is treated as the JSON value null when scanning; on marshal a nil JsonSlice is rendered as null too.

Index

• type JsonSlice
  • func (j JsonSlice) MarshalGQL(w io.Writer)
  • func (j JsonSlice) MarshalJSON() ([]byte, error)
  • func (j *JsonSlice) Scan(src any) error
  • func (j *JsonSlice) UnmarshalGQL(v any) error
  • func (j *JsonSlice) UnmarshalJSON(data []byte) error
  • func (j JsonSlice) Value() (driver.Value, error)

Types

type JsonSlice

type JsonSlice []any

JsonSlice is a slice of arbitrary JSON values.

func (JsonSlice) MarshalGQL

func (j JsonSlice) MarshalGQL(w io.Writer)

MarshalGQL is the gqlgen-compatible marshal hook. gqlgen detects this method by name; we therefore need not import gqlgen. Errors are rare (the slice already round-tripped through JSON to reach a resolver) and would indicate a programmer error encoding an unsupported type into the slice — those are surfaced by writing an empty array, never panicking inside a request goroutine.

func (JsonSlice) MarshalJSON

func (j JsonSlice) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. A nil slice marshals to the JSON value null; an empty non-nil slice marshals to [].

func (*JsonSlice) Scan

func (j *JsonSlice) Scan(src any) error

Scan implements [sql.Scanner]. Accepts []byte, string, or nil. NULL scans into a nil slice.

func (*JsonSlice) UnmarshalGQL

func (j *JsonSlice) UnmarshalGQL(v any) error

UnmarshalGQL is the gqlgen-compatible unmarshal hook. It accepts the already-parsed JSON value gqlgen passes (a []any for a JSON array, or a scalar that the receiver chooses to wrap), re-encodes it, and decodes into the slice.

func (*JsonSlice) UnmarshalJSON

func (j *JsonSlice) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. The JSON value null deserialises to a nil slice.

func (JsonSlice) Value

func (j JsonSlice) Value() (driver.Value, error)

Value implements driver.Valuer. The zero / nil slice persists as SQL NULL; otherwise the slice is encoded as a JSON array.