refactor: disambiguate line children

LineChildren type was used for two reasons:
- Collection of invoice lines (with the option of being expanded)
- Collection of detailed lines (expand does not make sense)

This patch makes sure that we have seperate types as perparation for
the introduction of specific detailed line types.

Author: turip

openmeter/billing/adapter/invoice.go

@@ -552,7 +552,7 @@ func (a *adapter) UpdateInvoice(ctx context.Context, in billing.UpdateInvoiceAda
 			return in, err
 		}
 
-		updatedLines := billing.LineChildren{}
+		updatedLines := billing.InvoiceLines{}
 		if in.Lines.IsPresent() {
 			// Note: this only supports adding new lines or setting the DeletedAt field
 			// we don't support moving lines between invoices here, as the cross invoice
@@ -567,14 +567,14 @@ func (a *adapter) UpdateInvoice(ctx context.Context, in billing.UpdateInvoiceAda
 				return in, err
 			}
 
-			updatedLines = billing.NewLineChildren(lines)
+			updatedLines = billing.NewInvoiceLines(lines)
 		}
 
 		// Let's return the updated invoice
 		if !in.ExpandedFields.DeletedLines && updatedLines.IsPresent() {
 			// If we haven't requested deleted lines, let's filter them out, as if there were lines marked deleted
 			// the adapter update would return them as well.
-			updatedLines = billing.NewLineChildren(
+			updatedLines = billing.NewInvoiceLines(
 				lo.Filter(updatedLines.OrEmpty(), func(line *billing.Line, _ int) bool {
 					return line.DeletedAt == nil
 				}),
@@ -761,7 +761,7 @@ func (a *adapter) mapInvoiceFromDB(ctx context.Context, invoice *db.BillingInvoi
 			return billing.Invoice{}, err
 		}
 
-		res.Lines = billing.NewLineChildren(mappedLines)
+		res.Lines = billing.NewInvoiceLines(mappedLines)
 	}
 
 	if len(invoice.Edges.BillingInvoiceValidationIssues) > 0 {

openmeter/billing/adapter/invoicelinediff.go

@@ -179,7 +179,7 @@ func diffInvoiceLines(lines []*billing.Line) (*invoiceLineDiff, error) {
 		}
 
 		// Any child of a new item is also new => let's create them
-		for _, child := range workItem.Children.OrEmpty() {
+		for _, child := range workItem.Children {
 			diff.ChildrenDiff.LineBase.NeedsCreate(child)
 			switch child.Type {
 			case billing.InvoiceLineTypeFee:
@@ -197,13 +197,13 @@ func diffInvoiceLines(lines []*billing.Line) (*invoiceLineDiff, error) {
 	// Let's figure out what we need to do about child lines
 	for _, childUpdate := range childUpdates {
 		// If the children are not present, we don't need to do anything (a.k.a. do not touch)
-		if !childUpdate.Children.IsPresent() {
+		if len(childUpdate.Children) == 0 {
 			continue
 		}
 
 		if err := getChildrenActions(
-			childUpdate.DBState.Children.OrEmpty(),
-			childUpdate.Children.OrEmpty(),
+			childUpdate.DBState.Children,
+			childUpdate.Children,
 			diff.ChildrenDiff,
 		); err != nil {
 			outErr = errors.Join(outErr, err)
@@ -255,11 +255,9 @@ func diffLineBaseEntities(line *billing.Line, out *invoiceLineDiff) error {
 			out.LineBase.NeedsDelete(line)
 			out.AffectedLineIDs.Add(getParentIDAsSlice(line)...)
 
-			if line.Children.IsPresent() {
-				// We need to delete the children as well
-				if err := deleteLineChildren(line, out); err != nil {
-					return err
-				}
+			// We need to delete the children as well
+			if err := deleteLineChildren(line, out); err != nil {
+				return err
 			}
 
 			if err := handleLineDependantEntities(line, operationDelete, out); err != nil {
@@ -363,7 +361,7 @@ func getChildrenActions(dbSave []*billing.Line, current []*billing.Line, out *in
 }
 
 func deleteLineChildren(line *billing.Line, out *invoiceLineDiff) error {
-	for _, child := range line.DBState.Children.OrEmpty() {
+	for _, child := range line.DBState.Children {
 		out.ChildrenDiff.LineBase.NeedsDelete(child)
 
 		if err := handleLineDependantEntities(child, operationDelete, out.ChildrenDiff); err != nil {

openmeter/billing/adapter/invoicelinediff_test.go

@@ -461,7 +461,7 @@ func cloneLines(lines []*billing.Line) []*billing.Line {
 
 func fixParentReferences(lines []*billing.Line) []*billing.Line {
 	for _, line := range lines {
-		for _, child := range line.Children.OrEmpty() {
+		for _, child := range line.Children {
 			child.ParentLineID = lo.ToPtr(line.ID)
 			child.ParentLine = line
 		}

openmeter/billing/adapter/invoicelinemapper.go

@@ -73,7 +73,7 @@ func (a *adapter) mapInvoiceLineFromDB(ctx context.Context, in mapInvoiceLineFro
 			entity.ParentLine = parent
 			// We only add children references if we know that those has been properly resolved
 			if _, ok := resolvedChildrenOfIDs[parent.ID]; ok {
-				parent.Children.Append(entity)
+				parent.Children = append(parent.Children, entity)
 			}
 		}
 	}
@@ -85,13 +85,6 @@ func (a *adapter) mapInvoiceLineFromDB(ctx context.Context, in mapInvoiceLineFro
 			return nil, fmt.Errorf("missing entity[%s]", dbEntity.ID)
 		}
 
-		// Given that we did the one level deep resolution, all the children should be resolved
-		// if it's not present it means that the line has no children, but before we only rely on Append
-		// to set the Present flag implicitly.
-		if !entity.Children.IsPresent() {
-			entity.Children = billing.NewLineChildren(nil)
-		}
-
 		entity.SaveDBSnapshot()
 
 		result = append(result, entity)

openmeter/billing/adapter/invoicelines.go

@@ -156,13 +156,13 @@ func (a *adapter) UpsertInvoiceLines(ctx context.Context, inputIn billing.Upsert
 
 		// Step 3: Let's create the detailed lines
 		flattenedDetailedLines := lo.FlatMap(input.Lines, func(_ *billing.Line, idx int) []*billing.Line {
-			return input.Lines[idx].Children.OrEmpty()
+			return input.Lines[idx].Children
 		})
 
 		if len(flattenedDetailedLines) > 0 {
 			// Let's restore the parent <-> child relationship in terms of the ParentLineID field
 			for _, line := range input.Lines {
-				for _, child := range line.Children.OrEmpty() {
+				for _, child := range line.Children {
 					child.ParentLineID = lo.ToPtr(line.ID)
 				}
 			}

openmeter/billing/httpdriver/invoice.go

@@ -383,7 +383,7 @@ func (h *handler) SimulateInvoice() SimulateInvoiceHandler {
 
 				Number:   body.Number,
 				Currency: currencyx.Code(body.Currency),
-				Lines:    billing.NewLineChildren(lines),
+				Lines:    billing.NewInvoiceLines(lines),
 			}, nil
 		},
 		func(ctx context.Context, request SimulateInvoiceRequest) (SimulateInvoiceResponse, error) {

openmeter/billing/httpdriver/invoiceline.go

@@ -183,13 +183,7 @@ func mapTaxConfigToAPI(to *productcatalog.TaxConfig) *api.TaxConfig {
 	return lo.ToPtr(productcataloghttp.FromTaxConfig(*to))
 }
 
-func mapDetailedLinesToAPI(optChildren billing.LineChildren) (*[]api.InvoiceDetailedLine, error) {
-	if optChildren.IsAbsent() {
-		return nil, nil
-	}
-
-	children := optChildren.OrEmpty()
-
+func mapDetailedLinesToAPI(children billing.LineChildren) (*[]api.InvoiceDetailedLine, error) {
 	out := make([]api.InvoiceDetailedLine, 0, len(children))
 
 	for _, child := range children {
@@ -697,7 +691,7 @@ func mergeLineFromInvoiceLineReplaceUpdate(existing *billing.Line, line api.Invo
 	return existing, wasChange, nil
 }
 
-func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing.Invoice, updatedLines []api.InvoiceLineReplaceUpdate) (billing.LineChildren, error) {
+func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing.Invoice, updatedLines []api.InvoiceLineReplaceUpdate) (billing.InvoiceLines, error) {
 	linesByID, _ := slicesx.UniqueGroupBy(invoice.Lines.OrEmpty(), func(line *billing.Line) string {
 		return line.ID
 	})
@@ -716,11 +710,11 @@ func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing
 			// but we are not persisting them to the database
 			newLine, err := lineFromInvoiceLineReplaceUpdate(line, invoice)
 			if err != nil {
-				return billing.LineChildren{}, fmt.Errorf("failed to create new line: %w", err)
+				return billing.InvoiceLines{}, fmt.Errorf("failed to create new line: %w", err)
 			}
 
 			if newLine.Type == billing.InvoiceLineTypeFee {
-				return billing.LineChildren{}, billing.ValidationError{
+				return billing.InvoiceLines{}, billing.ValidationError{
 					Err: fmt.Errorf("creating flat fee lines is not supported, please use usage based lines instead"),
 				}
 			}
@@ -731,7 +725,7 @@ func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing
 					Line:    newLine,
 				})
 				if err != nil {
-					return billing.LineChildren{}, fmt.Errorf("failed to snapshot quantity: %w", err)
+					return billing.InvoiceLines{}, fmt.Errorf("failed to snapshot quantity: %w", err)
 				}
 			}
 
@@ -742,11 +736,11 @@ func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing
 		foundLines.Add(id)
 		mergedLine, changed, err := mergeLineFromInvoiceLineReplaceUpdate(existingLine, line)
 		if err != nil {
-			return billing.LineChildren{}, fmt.Errorf("failed to merge line: %w", err)
+			return billing.InvoiceLines{}, fmt.Errorf("failed to merge line: %w", err)
 		}
 
 		if changed && mergedLine.Type == billing.InvoiceLineTypeFee {
-			return billing.LineChildren{}, billing.ValidationError{
+			return billing.InvoiceLines{}, billing.ValidationError{
 				Err: fmt.Errorf("updating flat fee lines is not supported, please use usage based lines instead"),
 			}
 		}
@@ -757,7 +751,7 @@ func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing
 				Line:    mergedLine,
 			})
 			if err != nil {
-				return billing.LineChildren{}, fmt.Errorf("failed to snapshot quantity: %w", err)
+				return billing.InvoiceLines{}, fmt.Errorf("failed to snapshot quantity: %w", err)
 			}
 		}
 
@@ -773,5 +767,5 @@ func (h *handler) mergeInvoiceLinesFromAPI(ctx context.Context, invoice *billing
 		out = append(out, existingLine)
 	}
 
-	return billing.NewLineChildren(out), nil
+	return billing.NewInvoiceLines(out), nil
 }

openmeter/billing/invoice.go

@@ -332,7 +332,7 @@ type Invoice struct {
 	InvoiceBase `json:",inline"`
 
 	// Entities external to the invoice itself
-	Lines            LineChildren     `json:"lines,omitempty"`
+	Lines            InvoiceLines     `json:"lines,omitempty"`
 	ValidationIssues ValidationIssues `json:"validationIssues,omitempty"`
 
 	Totals Totals `json:"totals"`
@@ -410,7 +410,7 @@ func (i *Invoice) FlattenLinesByID() map[string]*Line {
 	for _, line := range i.Lines.OrEmpty() {
 		out[line.ID] = line
 
-		for _, child := range line.Children.OrEmpty() {
+		for _, child := range line.Children {
 			out[child.ID] = child
 		}
 	}
@@ -477,7 +477,7 @@ func (i *Invoice) SortLines() {
 
 	sortLines(lines)
 
-	i.Lines = NewLineChildren(lines)
+	i.Lines = NewInvoiceLines(lines)
 }
 
 func sortLines(lines []*Line) {
@@ -512,17 +512,106 @@ func sortLines(lines []*Line) {
 	})
 
 	for idx, line := range lines {
-		if line.Type == InvoiceLineTypeUsageBased && line.Children.IsPresent() {
-			children := line.Children.OrEmpty()
-			sortLines(children)
-
-			line.Children = NewLineChildren(children)
+		if line.Type == InvoiceLineTypeUsageBased {
+			sortLines(line.Children)
 		}
 
 		lines[idx] = line
 	}
 }
 
+type InvoiceLines struct {
+	mo.Option[[]*Line]
+}
+
+func NewInvoiceLines(children []*Line) InvoiceLines {
+	// Note: this helps with test equality checks
+	if len(children) == 0 {
+		children = nil
+	}
+
+	return InvoiceLines{mo.Some(children)}
+}
+
+func (i InvoiceLines) Validate() error {
+	return errors.Join(lo.Map(i.OrEmpty(), func(line *Line, idx int) error {
+		return ValidationWithFieldPrefix(fmt.Sprintf("%d", idx), line.Validate())
+	})...)
+}
+
+func (c InvoiceLines) Map(fn func(*Line) *Line) InvoiceLines {
+	if !c.IsPresent() {
+		return c
+	}
+
+	return InvoiceLines{
+		mo.Some(
+			lo.Map(c.OrEmpty(), func(item *Line, _ int) *Line {
+				return fn(item)
+			}),
+		),
+	}
+}
+
+func (c InvoiceLines) Clone() InvoiceLines {
+	return c.Map(func(l *Line) *Line {
+		return l.Clone()
+	})
+}
+
+func (c InvoiceLines) GetByID(id string) *Line {
+	return lo.FindOrElse(c.Option.OrEmpty(), nil, func(line *Line) bool {
+		return line.ID == id
+	})
+}
+
+func (c *InvoiceLines) ReplaceByID(id string, newLine *Line) bool {
+	if c.IsAbsent() {
+		return false
+	}
+
+	lines := c.OrEmpty()
+
+	for i, line := range lines {
+		if line.ID == id {
+			// Let's preserve the DB state of the original line (as we are only replacing the current state)
+			originalDBState := line.DBState
+
+			lines[i] = newLine
+			lines[i].DBState = originalDBState
+			return true
+		}
+	}
+
+	return false
+}
+
+// NonDeletedLineCount returns the number of lines that are not deleted and have a valid status (e.g. we are ignoring split lines)
+func (c InvoiceLines) NonDeletedLineCount() int {
+	return lo.CountBy(c.OrEmpty(), func(l *Line) bool {
+		return l.DeletedAt == nil && l.Status == InvoiceLineStatusValid
+	})
+}
+
+func (c *InvoiceLines) Append(l ...*Line) {
+	c.Option = mo.Some(append(c.OrEmpty(), l...))
+}
+
+func (c *InvoiceLines) RemoveByID(id string) bool {
+	toBeRemoved := c.GetByID(id)
+	if toBeRemoved == nil {
+		return false
+	}
+
+	c.Option = mo.Some(
+		lo.Filter(c.Option.OrEmpty(), func(l *Line, _ int) bool {
+			return l.ID != id
+		}),
+	)
+
+	return true
+}
+
 type InvoiceExternalIDs struct {
 	Invoicing string `json:"invoicing,omitempty"`
 	Payment   string `json:"payment,omitempty"`
@@ -959,7 +1048,7 @@ type SimulateInvoiceInput struct {
 
 	Number   *string
 	Currency currencyx.Code
-	Lines    LineChildren
+	Lines    InvoiceLines
 }
 
 func (i SimulateInvoiceInput) Validate() error {
@@ -991,7 +1080,7 @@ func (i SimulateInvoiceInput) Validate() error {
 		return errors.New("currency is required")
 	}
 
-	if i.Lines.IsAbsent() || len(i.Lines.OrEmpty()) == 0 {
+	if len(i.Lines.OrEmpty()) == 0 {
 		return errors.New("lines are required")
 	}
 

openmeter/billing/invoice_test.go

@@ -69,7 +69,7 @@ func TestSortLines(t *testing.T) {
 
 	require.Equal(t, *lines[0].Description, "index=0")
 	require.Equal(t, *lines[1].Description, "index=1")
-	children := lines[1].Children.OrEmpty()
+	children := lines[1].Children
 	require.Equal(t, *children[0].Description, "index=1.0")
 	require.Equal(t, *children[1].Description, "index=1.1")
 }