hackernews

README

hackernews

A pure-Go, dependency-free client for the official Hacker News Firebase API (https://hacker-news.firebaseio.com/v0/).

• CGO_ENABLED=0 — builds a static binary on every platform.
• Zero third-party dependencies — standard library only (net/http, encoding/json, context, fmt).
• Cross-compiles to all Go 64-bit targets (linux/{amd64,arm64,riscv64,ppc64le,s390x,loong64}, darwin/{amd64,arm64}, windows/amd64).
• 100% test coverage, network-free (net/http/httptest).

Install

go get github.com/go-hackernews/hackernews

Requires Go 1.26.4 or newer.

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/go-hackernews/hackernews"
)

func main() {
	ctx := context.Background()
	c := hackernews.New()

	// Fetch a single item.
	item, err := c.Item(ctx, 8863)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s by %s (%d points)\n", item.Title, item.By, item.Score)

	// Fetch the top 10 stories, fully resolved and in list order.
	stories, err := c.Stories(ctx, hackernews.Top, 10)
	if err != nil {
		log.Fatal(err)
	}
	for i, s := range stories {
		fmt.Printf("%2d. %s\n", i+1, s.Title)
	}

	// Just the ID lists are available too.
	ids, err := c.TopStories(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%d top-story IDs\n", len(ids))
}

Options

New accepts functional options:

c := hackernews.New(
	hackernews.WithHTTPClient(myClient),
	hackernews.WithBaseURL("http://127.0.0.1:8080/v0"),
	hackernews.WithUserAgent("my-app/1.0"),
)

Story kinds

Stories takes a StoryKind:

Constant	List endpoint
hackernews.Top	/topstories.json
hackernews.Newest	/newstories.json
hackernews.Best	/beststories.json

Note: the newest-stories constant is named Newest (not New) because New is the package's constructor function; Go does not allow a function and a constant to share a name in the same package.

Stories fetches the first limit IDs from the chosen list (a limit <= 0 means all of them) and resolves each Item concurrently, using a bounded pool of goroutines while preserving the original list order. An error on any single item aborts the batch and is returned wrapped, and context cancellation is propagated to all in-flight requests.

License

BSD-3-Clause — Copyright (c) the go-hackernews/hackernews authors.

Documentation

Overview

Package hackernews is a dependency-free client for the official Hacker News Firebase API (https://hacker-news.firebaseio.com/v0/).

It uses only the Go standard library and builds with CGO_ENABLED=0.

Index

• Constants
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) BestStories(ctx context.Context) ([]int, error)
  • func (c *Client) Item(ctx context.Context, id int) (*Item, error)
  • func (c *Client) NewStories(ctx context.Context) ([]int, error)
  • func (c *Client) Stories(ctx context.Context, kind StoryKind, limit int) ([]Item, error)
  • func (c *Client) TopStories(ctx context.Context) ([]int, error)
• type Item
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithUserAgent(ua string) Option
• type StoryKind

Constants

const DefaultBaseURL = "https://hacker-news.firebaseio.com/v0"

DefaultBaseURL is the base URL of the public Hacker News Firebase API.

const DefaultUserAgent = "go-hackernews/hackernews (+https://github.com/go-hackernews/hackernews)"

DefaultUserAgent is sent on every request unless overridden.

Types

type Client

type Client struct {
	HTTPClient *http.Client
	BaseURL    string
	UserAgent  string
}

Client is a Hacker News API client. Use New to construct one.

func New

func New(opts ...Option) *Client

New returns a Client with sane defaults (the public API base URL and http.DefaultClient), then applies opts in order.

func (*Client) BestStories

func (c *Client) BestStories(ctx context.Context) ([]int, error)

BestStories returns the IDs of the best stories.

func (*Client) Item

func (c *Client) Item(ctx context.Context, id int) (*Item, error)

Item fetches a single item by ID.

func (*Client) NewStories

func (c *Client) NewStories(ctx context.Context) ([]int, error)

NewStories returns the IDs of the newest stories.

func (*Client) Stories

func (c *Client) Stories(ctx context.Context, kind StoryKind, limit int) ([]Item, error)

Stories fetches the first limit IDs from the given list and resolves each Item concurrently, preserving the list order. A limit <= 0 means all IDs. An error fetching any individual item aborts and is returned wrapped.

func (*Client) TopStories

func (c *Client) TopStories(ctx context.Context) ([]int, error)

TopStories returns the IDs of the current top stories.

type Item

type Item struct {
	ID          int    `json:"id"`
	Type        string `json:"type"` // "story","comment","job","poll",...
	By          string `json:"by"`
	Time        int64  `json:"time"` // unix seconds
	Text        string `json:"text"` // HTML, for text posts/comments
	URL         string `json:"url"`  // external link for stories
	Title       string `json:"title"`
	Score       int    `json:"score"`
	Descendants int    `json:"descendants"` // total comment count
	Kids        []int  `json:"kids"`
	Deleted     bool   `json:"deleted"`
	Dead        bool   `json:"dead"`
}

Item is a Hacker News item: a story, comment, job, poll, or poll option.

type Option

type Option func(*Client)

Option customizes a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (useful for testing).

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the underlying *http.Client.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header sent on each request.

type StoryKind

type StoryKind string

StoryKind selects a story list.

const (
	// Top selects the top stories list.
	Top StoryKind = "top"
	// Newest selects the newest stories list.
	//
	// NOTE: the required API named this constant "New", but that collides with
	// the New constructor function in the same package (an unavoidable Go name
	// clash), so it is exported as Newest. Its string value is still "new".
	Newest StoryKind = "new"
	// Best selects the best stories list.
	Best StoryKind = "best"
)