types

package module
v0.0.0-...-3d84a2e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 23, 2023 License: MIT-0 Imports: 5 Imported by: 4

README

Common Types

A number of basic type structures are shared across the poc-gcp-ecomm project; things like Money and Person, etc. All of those are defined here.

This module contains very little code, typically only that required to convert to and from these internal structures and their Protocol Buffer equivalents.

Why do we need two representations of essentially the same things? The Protocol Buffer structures are generated while these internal structures are annotated for saving and loading into and out of Firestore.

Documentation

Overview

Package types defines generic type entity structures as they might be stored in a Google Datastore or represented in JSON

Package types defines generic type entity structures as they might be stored in a Google Datastore or represented in JSON

Index

Constants

View Source
const (
	// KeyPrefixPerson may be combined with a person's UUID ID to form the datastore key name for a person entity
	KeyPrefixPerson = "person:"
)
View Source
const (
	// KeyPrefixPostalAddress may be combined with a postal address's UUID ID to form the datastore key name for a postal address entity
	KeyPrefixPostalAddress = "postaladdress:"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Money

type Money struct {

	// The three-letter currency code defined in ISO 4217.
	CurrencyCode string `firestore:"currencyCode,omitempty" json:"currencyCode,omitempty"`

	// The whole units of the amount.
	// For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
	Units int64 `firestore:"units,omitempty" json:"units,omitempty"`

	// Number of nano (10^-9) units of the amount.
	// The value must be between -999,999,999 and +999,999,999 inclusive.
	// If `units` is positive, `nanos` must be positive or zero.
	// If `units` is zero, `nanos` can be positive, zero, or negative.
	// If `units` is negative, `nanos` must be negative or zero.
	// For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
	Nanos int32 `firestore:"nanos,omitempty" json:"nanos,omitempty"`
}

Money is a representation of a currency value that can be directly mapped to the Google APIs protocol buffer representation of money.

Why not use the Google APIs Money structure directly? Well, it includes a mutex which makes it difficult / dangerous to copy and gives rise to compiler warnings. It also lacks the manipulation methods that we might want to add at some point (e.g. like those offered by https://github.com/Rhymond/go-money).

And finally, we want control over how the structure might be stored in a Google Cloud Datastore and JSON.

func MoneyFromPB

func MoneyFromPB(pbm *pbmoney.Money) *Money

MoneyFromPB is a factory method that generates a Money structure from its Protocol Buffer equivalent

If nil is passed in then nil will be returned. This saves the caller from having to check an error that can only occur if the caller is an idiot. Moral: do not pass in nil :-)

func (*Money) AsPBMoney

func (m *Money) AsPBMoney() *pbmoney.Money

AsPBMoney returns the protocol buffer representation of this Money.

type Person

type Person struct {
	Id               string `firestore:"id,omitempty" json:"id,omitempty"`
	FamilyName       string `firestore:"familyName,omitempty" json:"familyName,omitempty"`
	GivenName        string `firestore:"givenName,omitempty" json:"givenName,omitempty"`
	MiddleName       string `firestore:"middleName,omitempty" json:"middleName,omitempty"`
	DisplayName      string `firestore:"displayName,omitempty" json:"displayName,omitempty"`
	DisplayLastFirst string `firestore:"displayNameLastFirst,omitempty" json:"displayNameLastFirst,omitempty"`
}

Person describes a human individual

See https://developers.google.com/people/api/rest/v1/people#Person.Name as field naming reference.

func PersonFromPB

func PersonFromPB(pbPerson *pb.Person) *Person

PersonFromPB is a factory method that generates a Person structure from its Protocol Buffer equivalent

If nil is passed in then nil will be returned. This saves the caller from having to check an error that can only occur if the caller is an idiot. Moral: do not pass in nil :-)

func (*Person) AsPBPerson

func (p *Person) AsPBPerson() *pb.Person

AsPBPerson returns the protocol buffer representation of this Person.

type PostalAddress

type PostalAddress struct {
	// RegionCode (Required) id the  CLDR region code of the country/region of the
	// address. This is never inferred and it is up to the user to ensure the value
	// is correct. See http://cldr.unicode.org/ and
	// http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html
	// for details. Example: "CH" for Switzerland.
	RegionCode string `firestore:"regionCode,omitempty" json:"regionCode,omitempty"`

	// LanguageCode (Optional) is BCP-47 language code of the contents of this address
	// (if known). This is often the UI language of the input form or is expected
	// to match one of the languages used in the address' country/region, or their
	// transliterated equivalents.
	// This can affect formatting in certain countries, but is not critical
	// to the correctness of the data and will never affect any validation or
	// other non-formatting related operations.
	//
	// If this value is not known, it should be omitted (rather than specifying a
	// possibly incorrect default).
	//
	// Examples: "zh-Hant", "ja", "ja-Latn", "en".
	LanguageCode string `firestore:"languageCode,omitempty" json:"languageCode,omitempty"`

	// PostalCode (Optional) is the postal code of the address. Not all countries use or
	// require postal codes to be present, but where they are used, they may trigger
	// additional validation with other parts of the address (e.g. state/zip
	// validation in the U.S.A.).
	PostalCode string `firestore:"postalCode,omitempty" json:"postalCode,omitempty"`

	// SortingCode (Optional) is additional, country-specific, sorting code. This is not
	// used in most regions. Where it is used, the value is either a string like
	// "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number
	// alone, representing the "sector code" (Jamaica), "delivery area indicator"
	// (Malawi) or "post office indicator" (e.g. Côte d'Ivoire).
	SortingCode string `firestore:"sortingCode,omitempty" json:"sortingCode,omitempty"`

	// AdministrativeArea (Optional) is the highest administrative subdivision which
	//  is used for postal addresses of a country or region.
	// For example, this can be a state, a province, an oblast, or a prefecture.
	// Specifically, for Spain this is the province and not the autonomous
	// community (e.g. "Barcelona" and not "Catalonia").
	// Many countries don't use an administrative area in postal addresses. E.g.
	// in Switzerland this should be left unpopulated.
	AdministrativeArea string `firestore:"administrativeArea,omitempty" json:"administrativeArea,omitempty"`

	// Locality (Optional) generally refers to the city/town portion of the address.
	// Examples: US city, IT comune, UK post town.
	// In regions of the world where localities are not well defined or do not fit
	// into this structure well, leave locality empty and use address_lines.
	Locality string `firestore:"locality,omitempty" json:"locality,omitempty"`

	// Sublocality (Optional) is a subdivision of the locality of the address.
	// For example, this can be neighborhoods, boroughs, districts.
	Sublocality string `firestore:"sublocality,omitempty" json:"sublocality,omitempty"`

	// AddressLines (Optional) are unstructured address lines describing the lower
	// levels of an address.
	//
	// Because values in address_lines do not have type information and may
	// sometimes contain multiple values in a single field (e.g.
	// "Austin, TX"), it is important that the line order is clear. The order of
	// address lines should be "envelope order" for the country/region of the
	// address. In places where this can vary (e.g. Japan), address_language is
	// used to make it explicit (e.g. "ja" for large-to-small ordering and
	// "ja-Latn" or "en" for small-to-large). This way, the most specific line of
	// an address can be selected based on the language.
	//
	// The minimum permitted structural representation of an address consists
	// of a region_code with all remaining information placed in the
	// address_lines. It would be possible to format such an address very
	// approximately without geocoding, but no semantic reasoning could be
	// made about any of the address components until it was at least
	// partially resolved.
	//
	// Creating an address only containing a region_code and address_lines, and
	// then geocoding is the recommended way to handle completely unstructured
	// addresses (as opposed to guessing which parts of the address should be
	// localities or administrative areas).
	AddressLines []string `firestore:"addressLines,omitempty" json:"addressLines,omitempty"`

	// Recipients (Optional) are the recipients at the address.
	// This field may, under certain circumstances, contain multiline information.
	// For example, it might contain "care of" information.
	Recipients []string `firestore:"recipients,omitempty" json:"recipients,omitempty"`

	// Organization (Optional) is the name of the organization (e.g. business) at
	// the address.
	Organization string `firestore:"organization,omitempty" json:"organization,omitempty"`

	// MailboxId (Optional) is the identifier of a mailbox at this address. Used in the
	// case where multiple entities may be registered at the same address, divided
	// by per entity delivery boxes.
	//
	// Some address values might specify the mailbox as an address line but this field
	// allows for a mailbox to be explicitly labeled in the data.
	MailboxId string `firestore:"mailboxId,omitempty" json:"mailboxId,omitempty"`
}

PostalAddress represents a postal address, e.g. for postal delivery or payments addresses. Given a postal address, a postal service can deliver items to a premise, P.O. Box or similar. It is not intended to model geographical locations (roads, towns, mountains).

In typical usage an address would be created via user input or from importing existing data, depending on the type of process.

Advice on address input / editing:

For more guidance on how to use this schema, please see: https://support.google.com/business/answer/6397478

func PostalAddressFromPB

func PostalAddressFromPB(p *pb.PostalAddress) *PostalAddress

PostalAddressFromPB is a factory method that generates a PostalAddress structure from its Protocol Buffer equivalent

If nil is passed in then nil will be returned. This saves the caller from having to check an error that can only occur if the caller is an idiot. Moral: do not pass in nil :-)

func (*PostalAddress) AsPBPostalAddress

func (p *PostalAddress) AsPBPostalAddress() *pb.PostalAddress

AsPBPostalAddress returns the protocol buffer representation of this Person.

type Timestamp

type Timestamp interface {

	// GetTime returns the underlying time.Time value.
	GetTime() time.Time

	// GetPBTimestamp returns the time value as a google.protobuf.Timestamp protocol
	// buffer value.
	GetPBTimestamp() *timestamppb.Timestamp

	// String returns the time value as an RFC 3339 UTC string value to nanosecond accuracy.
	String() string
}

Timestamp defines the interface for a time structure capable of capturing a time as either an RFC 3339 UTC string or a google.protobuf.Timestamp protocol buffer value.

func NewTimestamp

func NewTimestamp(t time.Time) Timestamp

NewTimestamp is a factory method returning a Timestamp value reference for a given time.

func TimestampFromPBTimestamp

func TimestampFromPBTimestamp(timepb *timestamppb.Timestamp) (Timestamp, error)

TimestampFromPBTimestamp is a factory method returning a Timestamp value reference set to translation of a Google protocol buffer timestamp value. If the value cannot be translated (i.e. if the input is not a valid time representation) then an error is returned.

func TimestampFromRFC3339Nano

func TimestampFromRFC3339Nano(timeStr string) (Timestamp, error)

TimestampFromRFC3339Nano is a factory method returning a Timestamp value reference set to parsed value of an UTC RFC 3339 string accurate to a nanosecond. If the supplied time cannot be parsed, an error is returned.

func TimestampNow

func TimestampNow() Timestamp

TimestampNow is a factory method returning a Timestamp value reference to the time right now.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL